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Preface 



The Apple III Pascal Technical Reference Manual \s a technical reference for 
more advanced users of the Apple III Pascal system. It describes the 
architecture and operation of the P-machine, operating system, and I/O of the 
Apple III Pascal system. Before you use the information it contains, you should 
be familiar with these manuals: 

Apple III SOS Reference Manual 

Apple III Pascal: Introduction, Filer, and Editor 

Apple III Pascal Programmer's Manual, Volumes 1 and 2 

Apple III Pascal Program Preparation Tools 

Many of the concepts explained in this volume are intimately interrelated. You 
should first briefly read the entire book and gain an appreciation of how the 
concepts are interrelated before attempting to understand any specific 
concept in detail. Here is a brief description of the contents: 

• Chapter 1 is an overview of the Apple III Pascal system. 

• Chapter 2 describes the structure and format of codefiles on disk. 

• Chapter 3 describes the structure and format of code in memory, and 
the operation of the P-machine. 

• Chapter 4 details the use of assembly-language procedures and 
functions. 

• Chapter 5 describes the P-machine instruction set. 




• Chapter 6 contains useful assembly-language and Pascal 
programming techniques and hints. 

A glossary and an index are also included. Any item that appears in the 
Glossary is shown in boldface type at its first occurrence in the text of this 
manual. 

You should be familiar with the hexadecimal numbering system. Hexadecimal 
numbers in the text and tables of this manual are preceded by a dollar sign ($). 
In the text or in a table or illustration, any number that is not preceded by a 
dollar sign is a decimal number. 

Two special symbols are used in this manual to draw your attention to 
particular items of information: 



The pointing hand indicates something particularly interesting or useful. 




[<J»}>) The eye indicates points you need to be cautious about. 
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Overview 



The Pascal Environment 



The Apple III Pascal system is a version of the UCSD Pascal system, a 
psuedo-machine-based implementation of Pascal . This means that the 
Compiler converts Pascal program text into compact pseudo-code or P-code 
to be executed by the pseudo-machine or P-machlne. The P-machine is 
implemented by the Pascal interpreter— a program written in the native code 
of the Apple Ill's 6502 microprocessor. Every host computer operating under 
a version of UCSD Pascal has such an interpreter that makes the host 
computer appear, from the viewpoint of a program being executed, to be a P- 
machine. The Interpreter is contained in the SOS.INTERP file on the 
PASCAL1 disk. 

The Pascal operating system and various utility programs are also written in 
Pascal and run on the same interpreter. The Pascal system runs "on top of" 
SOS, the Apple III operating system. (See the Apple III SOS Reference 
Manual for a detailed explanation of this relationship.) 

The Pascal Compiler, Assembler, and Linker together produce completed 
codef iles of Pascal programs. Pascal codefiles are stored on external storage 
media, such as disks. The structure of codefiles is explained in Chapter 2. 
When a Pascal program is to be executed, the interpreter loads the code of 
the user program main segment of the codefile into memory, and then begins 
executing the program code, one instruction at a time. As the interpreter finds 
that additional segments of the disk codefile are needed in memory for 
execution of the program, it loads the necessary segments. The structure and 
execution of code in memory is described in Chapter 3. Pascal programs can 
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contain assembly-language procedures and functions; these are discussed in 
Chapter 4. The P-machine instruction set is described in Chapter 5. A group 
of useful Pascal and assembly-language programming techniques are 
discussed in Chapter 6. 
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Codefiles 



Codefiles may be (1 ) linked files composed of segments ready for 
execution, (2) library files with units which may be used by programs in other 
codefiles, or (3) unlinked files created by the Compiler or Assembler. A 
typical disk codefile resulting from the compilation of a program is diagrammed 
in Figure 2-1 . 



high disk addresses 



first segment 



sixteenth segment 



fifteenth segment 



third segment 



second segment 



segment dictionary 



low disk addresses 
Figure 2-1 . A Typical Codefile on Disk 
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All codefiles (linked and unlinked) consist of a segment dictionary in block 
of the codefile, followed by a sequence of one to 1 6 code segments. The 
host program is compiled into one code segment, and each SEGMENT 
procedure, SEGMENT function, and unit is translated into another code 
segment. The ordering of code segments in the codefile (from low disk 
address to high disk address) is determined by the order in which the Compiler 
encounters the executable code of each SEGMENT procedure, SEGMENT 
function, and unit when compiling a program. This order may be changed by 
the Librarian. 

Each segment begins on a boundary between disk blocks (a blocic is 51 2 
contiguous bytes). Each segment may occupy up to 64 blocks. 

Segments 



A segment is either a code segment or a data segment. Program code is 
stored in code segments. Every program consists of at least one code 
segment, and some programs consist of many code segments. A code 
segment may contain either P-code, native 6502 code, or a combination of 
both. Code segments may have three parts: interface text, actual P-code 
and/or native code, and Linker information (Figure 2-2). These parts appear 
in this order on the disk, although not all types of code segments have all three 
parts. For example, interface text is present only in the code segments of 
units. Code segments may be either linked or unlinked. 

Data segments are areas of memory that are set aside at execution time as 
storage space for the local data of intrinsic units. In a disk codefile, data 
segments have only an entry in the segment dictionary: they do not occupy 
any blocks on the disk since they have no code part, interface text, or Linker 
information associated with them. 
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high disk addresses 



Second 






Code 
Segment 


Block 6 


interface text 




Block 5 


Linker information 




Block 4 


code part 




Block 3 






Block 2 


interface text 


First 

Code 

Segment 




(unit segments only) 


Block 1 




Block 


segment dictionary 



byte 51 1 
byte 



low disk addresses 



Figure 2-2. A Typical Codefile 

Note that Figure 2-2 is not meant to imply that all code segments are five 
blocks long; the code part of a segment can contain up to 64 blocks. 

Whenever a complete program codefile is produced by the Compiler (and 
Assembler and Linker, if necessary), the following occur: 

• The user program or unit results in one code segment in the codefile. 
This includes the user program's non-SEGMENT procedures and 
functions (MULT2 and STOR in Figure 2-3), and the user program 
body itself (MAIN in Figure 2-3). 

• Each Pascal SEGM ENT procedure or function results in a another 
code segment in the codefile (BYFOUR and DIVID below). 

• Each regular unit that the program USES is linked with the codefile 
and results in a code segment in the codefile (REGUNIT below). Each 
intrinsic unit that the program USES does not produce additional code 



segments in the program's codefile. Intrinsic units are held as 
segments in program libraries, shared libraries, and the 
SYSTEM.LIBRARY file, and accessed by the program at execution 
time (MAINLIBIU below). 



Source text files 



PROGRAM MAIN; 

USES MAINLIBIU. REGUNIT; 
SEGMENT FUNCTION DIVID; 
BEGIN 



END; 

SEGMENT PROCEDURE BYFOUR; 
BEGIN 



END; 



FUNCTION MULT2; 
BEGIN 



END; 



PROCEDURE STOR; 
BEGIN 



END; 



Segments in codefile 
after linking 



REGUNIT code segment 



MAIN "outer" code segment 
MULT2 function 
STOR procedure 



BYFOUR code segment 



DIVID code segment 



BEGIN 



END. 



UNIT REGUNIT; 
BEGIN 



END. 



Segment in Library 



UNIT MAINUBIU; INTRINSIC 

CODE 40 DATA 41; 
BEGIN 



END. 



MAINUBIU code segment 



Figure 2-3. Correlation Between Programs and Segments in Codefiles 
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Segments are not nested In codefiles as they are In programs. Instead every 
segment is a separate contiguous area of code and does not contain any other 
segments. For example, if a SEGMENT procedure contains another 
SEGMENT procedure, the compiled result comprises two distinct code 
segments, even though they are nested lexically in the source program. 

Segmenting a program does not change the computation it performs. When a 
SEGMENT procedure, SEGMENT function, or intrinsic unit is called during the 
execution of a program, the interpreter checks to see if that segment is 
already in memory due to a previous (and still active) invocation of the 
segment. If it is, control is transferred and execution proceeds; if not, the 
appropriate code segment is loaded into memory from the disk codefile before 
the transfer of control takes place. When no more active invocations of a 
segment exist, its code is removed from memory. 

The following sections describe the portions of a code segment in greater 
detail. First the segment dictionary is described. Then the parts of a code 
segment are presented in the order in which they may occur in a codefile: the 
interface text, the code part, and finally the Linker information. The code part 
description is divided into sections describing the similarities and differences 
between the code parts of P-code and assembly-language procedures. 

Segment Dictionaries 

Every codefile (including library files) has a segment dictionary in block that 
contains information needed by the Pascal system to load and execute the 
segments in that codefile. A segment dictionary has 1 6 slots, each of which 
either contains information about one segment, or is empty. Each non-empty 
slot includes the segment's name, kind, size (in bytes), and location in the 
codefile. The location of a code segment is given as the block number of the 
first block in the code part (blocks in a codefile are numbered sequentially from 
zero, with block as the segment dictionary). The location of a data segment 
is given as zero. 

The information that describes each segment is contained in five different 
arrays within the segment dictionary. All information describing a segment is 
retrieved by selecting corresponding elements from each of these arrays. 
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Since a segment dictionary has 1 6 slots, numbered through 1 5, one 
codefile can contain at most 1 6 segments. Intrinsic units used by a program 
do not require entries in the segment dictionary of the program's codefile, 
because intrinsic unit code segments are in a library file, and appear in the 
library file's segment dictionary. Therefore, a program can have a maximum of 
1 6 segments, not counting segments from intrinsic units. Counting intrinsic 
units, the maximum number of segments is limited by the total number of 
segment numbers in the system (64). However, the system reserves eleven 
segment numbers (0, 2 through 6, and 59 through 63) for its own use. The 
remaining 53 segments may appear in a program codefile, a program library 
file, a SYSTEM. LIBRARY file, or library files specified in a library name file. 
Each of these codefiles can contain a maximum of 1 6 segments. 

The following Pascal-like record declaration represents a segment dictionary: 



RECORD 



DISKINFO: ARRAYC0..15] 
RECORD 

CODEADDR: INTEGER; 

CODELENG: INTEGER 
END; 

SEGNAME : 



(Location of code part) 
llength of code part) 



PACKED ARRAYC0. .73 OF 
{segment name ) 



ARRAY10..15] OF 
CHAR; 



SEGKIND: ARRAY [0..15] OF (type of segment} 



(LINKED, 
HOSTSEG, 
SEGPROC , 
UNITSEG, 
SEPRTSEG, 

UNLINKED-INTRINS, 

LINKED-INTRINS, 

DATASEG); 



{fully executable segment} 
{user program code segment} 
{unused} 

{compiled regular unit) 
{separate procedures and 
functions} 

{unlinked intrinsic unit} 
{Linked intrinsic unit} 
{data segment) 



TEXTADDR: ARRAYC0..153 OF INTEGER; 

firstbLock of interface 



{ address of the 
text, if any } 



SEGINFO: PACKED ARRAYC0..15] OF PACKED RECORD 



SE6NUM: 0..255; {segment number) 

MTYPE: 0..15; {machine type) 

UNUSED : . . 1 ; { unused } 

VERSION; 0..7 {version number) 



END; 



INTRINS-SEGS: SET OF 0..63; 



{intrinsic segment 
numbers needed for 
execution} 



INT-NAM-CHECKSUM: PACKED ARRAY [0..63] OF 
0. .255; {checksum } 

FILLER: PACKED ARRAY CI. .72] OF 0.255; {72 unused 

bytes f i L Led with 
zeros) 

COMMENT: PACKED ARRAY [0..79] OF CHAR {comment} 
END; 

The following diagram (Figure 2-4) indicates the structure of a segment 
dictionary: 
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DISK INFO 



low disk addresses 
high byte low byte 



CODEADDR (block number) 



CODELENG (in bytes) 



(segment 0) 



(segments 1-15) 



word 
1 



SEGNAME 



SEGKIND 



TEXTADDR 



SEGINFO 



TEXTADDR 



1 St character 


0th character 


32 


3rd character 


2nd character 


33 


6th character 


"'(seg0)- - — - - 
4th character 


34 


7 th character 


6th character 


35 




(segments 1-16) 




SEGKIND 


(segment 0) 


96 



(segments 1-16) 



(segment 0) 



(segments 1-15) 



VERSION I 



MTVPE 



SEGNUM (seg0) 



bit: 16 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0. 

(segments 1-15) 



INTRINS-SEGS bit: 16 14 13 12 1 1 10 9 8 7 6 6 4 3 2 1 
31 30 29 28 27 26 26 24 23 22 21 20 19 18 17 16 
47 46 46 44 43 42 41 40 39 38 37 36 36 34 33 32 
63 62 61 60 69 58 57 66 56 64 53 52 61 50 49 48 



INT-NAM- 
CHKSUM 



CHECKSUM (unit 1 ) 



CHECKSUM (unit 0) 



112 



128 



144 
145 
146 
147 



FILLER 



CHECKSUM (unit 63) 



CHECKSUM (unit 62) 



178 
178 

180 



COMMENT 



1 St character 



0th character 



216 



79th character 



78th character 



255 



high disk addresses 

Figure 2-4. A Segment Dictionary 
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Note that the diagram in Figure 2-4 shows lower addresses at the top (in 
contrast to others in this manual) to match the structure of the Pascal-like 
segment dictionary declaration. 

A segment dictionary is composed of five 1 6-element arrays (one element for 
each segment slot in the segment dictionary of a codefile), information on the 
intrinsic segments used by the codefile, and a comment. 

Each element in the DISKINFO array consists of two words that describe the 
length and location of the segment within the codefile. For code segments, 
the CODEADDR field contains the block number of the start of the code part, 
and the CODELENG field contains the number of bytes in the code part of the 
segment. For data segments, the CODEADDR field is zero, and the 
CODELENG field contains the number of bytes to be allocated for data at 
execution time (the length of the data segment). Unused slots have their 
CODEADDR and CODELENG fields set to zero (CODELENG =0 defines an 
empty slot). 

Each element of the SEGNAME array is an eight-character array which 
contains the first eight characters of the user program, unit, SEGMENT 
procedure, SEGMENT function, or assembly-language procedure name that 
was translated into the corresponding segment. If the name is shorter than 
eight characters, it is padded on the right by spaces; if the name is longer than 
eight characters, it is truncated to the first eight characters. Unused segment 
slots have SEGNAME fields filled with eight ASCII space characters. 

The SEGKIND array describes the type of segment. The possible values are: 

0: LINKED. A fully-executable segment. Either all references to 
regular or intrinsic units have been resolved by the Linker, or none 
were present. 

1 : HOSTSEG. The main segment of a user program with 
unresolved external references. 

2: SEGPROC. A SEGMENT procedure or function. This type is 
currently not used. 

3: UNITSEG. A compiled regular (as opposed to intrinsic) unit. 
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4 : SEPRTSEG . A separately assembled (set of) procedures or 
functions, Including EXTERNAL functions and procedures, and 
mixed segments of linked Pascal and assembly-language code. 
Assembly-language codefiles are always of this type. 

5: UNLINKED-INTRINS. An intrinsic unit containing unresolved calls 
to assembly-language procedures or functions. 

6: LINKED-INTRINS. An intrinsic unit properly linked with its called 
procedures and functions. 

7: DATASEG. A data segment of an intrinsic unit. The segment 
dictionary entry specifies the amount of data space (in bytes) to 
allocate. 

The TEXTADDR array of integers contains pointers to the block number of the 
start of the interface text of each regular or intrinsic unit. The last block number 
of the interface text can be calculated by subtracting 1 from the value in the 
corresponding CODEADDR field. Interface text is described in detail below. 
Only unit segments have interface text; the TEXTADDR field is zero for all 
other types of segments. 

The SEGINFO array contains one word of additional information about each 
segment. Each word is composed of four fields: 

Bits through 7 (the low-order byte) of each word specify the segment 
number (SEGNUM). This is the position the code segment will occupy in 
the segment table at execution time. The segment table is 64 entries 
long, hence valid numbers for the SEGNUM field are©.. 63. (Segment 
tables are described in Chapter 3). 

Bits 8 through 1 1 of the second byte in the SEGINFO word specify the 
machine type (MTYPE) of the code in the segment. The machine types 
are: 

0: Unidentified code, perhaps from another Compiler. 
1 : P-code, most significant byte first. 
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2: P-code, least significant byte first (a stream of packed ASCII 
characters fills the low byte of a word first, then the high byte). 
This is the kind of P-code used by the Apple III. 

3 through 9: Assembled native code, produced from assembly- 
language text. Machine type 7 identifies native code for the 
Apple Ill's 6502 microprocessor. 

Bit 1 2 of the SEGINFO word is unused. 

Bits 1 3 through 1 5 of the SEGINFO word contain the version number of 
the system. The current version number is 3, indicating Apple III Pascal. 

The SEGINFO array is the last of the five arrays that contain 1 6 elements, one 
element for each slot. The remainder of the segment dictionary contains 
information pertinent to the execution of the entire codefile. 

The INTRINS-SEGS field consists of four words (64 bits). These four words 
specify which intrinsic units are needed to execute the codefile. Each intrinsic 
unit in a program library file, SYSTEM. LIBRARY file, and library file specified in 
a library name file, is identified by a segment number (or two segment numbers 
if the intrinsic unit has both a code and data segment). Each one of the 64 bits 
in these words corresponds to one of the 64 possible intrinsic segment 
numbers. If the nth bit is set, the codefile needs the intrinsic unit whose 
segment number is n in order to execute. Bits corresponding to the segment 
numbers of unused intrinsic units are zeroed. 

Some intrinsic units are part of the Pascal operating system. While their use is 
indicated by set bits in the INTRINS-SEGS field, they are not loaded from 
either the SYSTEM. LIBRARY or the program library, but are present at 
execution time. These special segments are numbered 59 through 63. 

The INT-NAM-CHECKSUM array contains 64 fields of 8-bit checksums of the 
names of the intrinsic units needed to execute the codefile. Each field 
corresponds to one of the 64 possible intrinsic segment numbers. These 
checksums are used by the Pascal operating system to ensure that two 
differently-named segments with identical segment numbers are not 
confused. The checksum is calculated by shifting the characters of the unit 
name to uppercase and summing the resulting ASCII values of the characters 
of the unit name MOD 256. The name is padded with spaces on the right if it is 



shorter than eight characters; it is truncated to eight characters if it is longer 
than eight characters. Padding spaces are included in the checksums. Words 
corresponding to the segment numbers of unused intrinsic segments are filled 
with blanks. 

The FILLER array contains 72 unused bytes. 

The COMMENT array contains text provided by a Compiler COMMENT 
option or when the Librarian is used. It starts in word 2 1 6 of the segment 
dictionary. 

Segment Numbers 

At execution time, every segment has a segment number from to 63, and no 
two segments in the program can have the same number. Segment numbers 
are assigned as follows (Figure 2-5): 

• the user program itself is segment 1 . 

• the segments used by the Pascal operating system are 0, 2 through 
6, and 59 through 63. These numbers are never assigned to 
segments of the user program. 

• the segment number of an intrinsic unit segment is determined by the 
unit's heading when the unit is compiled. (These numbers can be 
found by using the LIBMAP utility program to examine the segment 
dictionary of the library to which the unit belongs. 

• the segment numbers of regular unit segments and of SEGMENT 
procedures and functions within the program are automatically 
assigned by the system as the program is compiled and linked. The 
segment numbers of regular units and of SEGMENT procedures and 
functions begin at 7 and ascend. Note that after a regular unit is linked 
with a program , it may not have the same segment number that was 
shown for it in the library's segment dictionary (when examined with 
the LIBMAP utility), because the Linker may reassign segment 
numbers of regular units. 
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Segment 
Number 



Assignment 



2 
7 
30 
31 
32 
59 



6 

29 



58 
63 



Pascal operating system 

user program 

Pascal operating system 

units, SEGMENT procedures and functions 

PASCALIO unit 

LONGINTIO unit 

units, SEGMENT procedures and functions 
Pascal operating system 



Figure 2-5 



Segment Number Assignment 



Normally, only when writing an intrinsic unit do you need to specify segment 
numbers; this is explained in Chapter 1 4 of the Apple III Pascal Programmer's 
Manual. The choice must avoid the Pascal system segment numbers 
through 6 and 59 through 63, and numbers assigned to any other intrinsic unit 
which may be used in the same program as the unit being written. In addition, 
the standard library units PASCALIO and LONGINTIO occupy segment 
numbers 30 and 31 . Therefore, if you perform I/O of real numbers, long 
integer operations, or use the SEEK procedure, you cannot assign your own 
units segment numbers 30 and 31 . 




The PASCALIO and LONGINTIO standard library units are known to the 
Compiler and do not require a USES declaration. 



Intrinsic unit segment numbers must also avoid conflict with numbers which 
may be assigned automatically to regular units and SEGMENT procedures and 
functions. In other words, use high segment numbers for intrinsic units. 
However, when unavoidable conflicts arise, the NEXTSEG Compiler option 
described in the Apple III Pascal Programmer's Manual con be used to set the 
segment number to another value. (Segment numbers are discussed in further 
detail in conjunction with the section The Segment Table in Chapter 3.) 

Interface Text 

Code segments of units may have interface text before their code part; host 
segments, SEGMENT functions and procedures, and EXTERNAL 
procedures and functions never have interface text. The interface text 
contains the ASCII text of the INTERFACE section in the source text of a unit. 
The construction of an interface text of a segment from its source text (by the 
Compiler) is shown in Figure 2-6. 
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INTERFACE 
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USES TRANSCEND 
CONSTANT PI =3. 
CONSTANT E= 2. 7 
TYPEARRAYSIZE 
VARINRECORDil 
VAR CURRENT:CH 
PROCEDURE A; 
PROCEDURES; 
PROCEDURE C; 
FUNCTION D (IN 
FUNCTION E (AS 



FUNCTION F (PA 
IMPLEMENTATION 
PROCEDURE A; 



USESAPPLESTUF 
USES REALMODES 
garbage 



USES TRANSCEND 
CONSTANT PI =3. 
CONSTANTS =2. 7 
TYPE ARRAYSIZE 
VAR INRECORD:! 
VAR CURRENT:CH 
PROCEDURE A; 
PROCEDURE B; 
PROCEDURE C; 
FUNCTION D (IN 
FUNCTION E (AS 



FUNCTION F (PA 
IMPLEMENTATION 
unit info 



block m 



block m+1 



block m+2 



block m+3 



block m+4 



Figure 2-6. Construction of Interface Text in a Codefile 



The Pascal Compiler reads source text and produces interface text in two- 
block pages (1 024 bytes each). Interface text always starts on a page 
boundary and follows all of the conventions of a textfile, with the exception 
that the last page of the interface text may be either 1 or 2 blocks long. The 
interface text is identical to the source text, except for the first and last pages 
The information in the first page of the source text is truncated, such that the 
first character in the output page is the character following the INTERFACE 
keyword in the original source text ("U" in Figure 2-6). This may leave a 
considerable amount of unused space in the first page. The last page of the 
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source text is truncated after the IMPLEMENTATION keyword; it is possible 
that only one block of this page may be produced if the IMPLEMENTATION 
keyword occurs in the first block of the page. (IMPLEMENTATION is explained 
in the Apple III Pascal Programmer's Manual). Valid data in each page of a 
textfile end with a OR (ASCII 1 3) followed by at least one NULL (ASCII 0). 

The ten characters immediately following the IMPLEMENTATION keyword 
contain special unit info. All ten characters are ASCII spaces, except for an E 
in the ninth position, required by the Pascal Compiler and Librarian programs 
to terminate the interface text. A Pmay occur, instead of a space, in the 
second of the ten character positions to signify to the Pascal Compiler that the 
unit requires the PASCALIO standard library unit. The fourth position will be 
occupied by an L if the unit requires the LONGINTIO standard library unit. 
These items— IMPLEMENTATION, P, L, and E— are all considered tokens by 
the Compiler; thus, their order is significant, but their spacing and case are 
not. 

Interface text is not stripped of non-printing characters or comments. The 
comments are not necessary for execution, but leaving the comments in the 
interface text can lead to more complete internal program documentation at 
the expense of increased codefile length. Note that the interface text of unit 
segments is used only during compilation. Therefore, this text can be 
removed from completed codefiles that will only be executed. The effect is a 
reduction in codefile size. 

The TEXTADDR array of the segment dictionary contains pointers to the 
starting address of the interface text for each segment. The pointers specify 
block numbers, relative to the start of the codefile. The field is zero for 
segments that are not unit code segments, and unit segments that do not have 
an interface part. 

Code Parts 

The code part of a code segment consists of a group of procedures, together 
with descriptive information about the procedures, called the procedure 
dictionary. A code segment may contain up to 1 60 procedures, no more than 
1 49 of which can be P-code procedures (the remainder must be assembly- 
language procedures). Figure 2-7 is a diagram of the code part of a code 
segment. Each code part contains the code for the highest level procedure in 



the segment, as well as the code for each of the non-SEGMENT procedures 
and functions within the segment. The code of the highest level procedure, 
which is generated last, appears highest in the code part. 
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Figure 2-7. The Code Part of a Code Segment 
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Each procedure in a code part is assigned a procedure number starting at 1 , 
for the highest level procedure or SEGMENT procedure, and ranging as high 
as 1 49. All references to a procedure are made via its segment number and 
procedure number. Translation from a procedure number to the location of the 
procedure code in the code segment is accomplished via the procedure 
dictionary. 

Below the procedure dictionary is the code for the various procedures in the 
segment. The procedure dictionary grows downward toward lower disk 
addresses; the code part starts at the first byte of the block specified in the 
CODEADDR field of the segment dictionary and grows upward toward higher 
addresses. 

Procedure Dictionaries 

The position of the low-order byte of the highest word in a segment's 
procedure dictionary can be calculated as: 

CODEADDR * 512 + CODELENG - 2 

This highest word in a procedure dictionary contains the segment number in 
its low-order (even) byte, and the number of procedures in the segment in its 
high-order (odd) byte. Below this word is a sequence of words that contain 
self-relative pointers to the top (high address) of the code of each procedure in 
the segment (Figure 2-7). (A self-relative pointer contains the absolute 
distance, in bytes, between the low-order byte of the pointer and the low- 
order byte of the word to^hich it points. To find the address referred to by a 
self-relative pointer, subtract the pointer from the address of its location to find 
the byte pointed to.) 

A procedure's number is an index into the procedure dictionary: the nth word 
in the dictionary (counting downward from higher addresses) contains a 
pointer to the top (high address) of the code of procedure n. As zero is not a 
valid procedure number, the zeroth word of the dictionary is used to store the 
segment number of the code segment, and the number of procedures in that 
code segment (as described above). 



Procedures 



Each procedure consists of two parts: the procedure code itself (in the lower 
portion of the procedure growing up toward higher addresses), and an 
attribute table of the procedure. Some procedures have a third part called the 
jump table located at the base of the attribute table. Figure 2-8 is a diagram of 
a typical procedure. 

high disk or memory addresses 
high byte low byte 



attribute table 
(with optional jump table) 

t 

procedure 
code 



low disk or memory addresses 

Figure 2-8. A Typical Procedure 

ATTRIBUTE TABLES 

The attribute table of a procedure provides information needed to execute 
the procedure. Procedure attribute tables are pointed to by entries in the 
procedure dictionary of each segment. 

The Compiler produces P-code by compiling source text, and the Assembler 
produces native code by assembling assembly language. Procedures may 
contain solely P-code or native code, but not a mixture of both. It is possible to 
produce segments with procedures of both code types using the Linker. In 
this case the MTYPE field in the segment dictionary is set to the value for 
assembled native code (7), because the code for that segment is then 
machine-specific. The interpreter is able to determine the type of code in a 
particular procedure via information contained in the procedure's attribute 
table. The format of the attribute table for an assembly-language procedure is 
very different from that for a P-code procedure. These two formats are 
described in the following sections. 
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P-Code Procedure Attribute Tables 

The format of a P-code procedure attribute table is illustrated in Figure 2-9. 
high disk or memory addresses 



high byte low byte 



LEX LEVEL PROCEDURE NUMBER 




ENTERIC 




EXITIC 


PARAMETER SIZE (in bytes) 


DATA SIZE (in bytes) 


optional jump table 



pointers to code 

low disk or memory addresses 
Figure 2-9. P-Code Procedure Attribute Table 

The fields of a P-code procedure attribute table are: 

PROCEDURE NUMBER: This field contains the procedure number. 
The PROCEDURE NUMBER field is the low-order (even) byte of 
the highest word in the attribute table. 

LEX LEVEL: This field specifies the depth of lexical nesting of the 
procedure. The lexical level of the Pascal operating system is 
- 1 , the lexical level of a user program is 0, and that of the first 
nested procedure is 1 , and so forth. (See the Apple III Pascal 
Programmer's Manual, Volume 2). The LEX LEVEL field is the 
high-order (odd) byte of the highest word in the attribute table. 

ENTER IC: This field contains a self-relative pointer (again, a positive 
number, pointing back) to the first P-code instruction to be 
executed in the procedure. 



EXIT IC: This field contains a self-relative pointer to the beginning of the 
sequence of P-code instructions that must be executed to 
terminate the procedure properly. 

PARAMETER SIZE: This field specifies the number of bytes of 

parameters passed to a procedure from its calling procedure. If the 
procedure is a function, this number includes the number of bytes 
to be reserved for the returned value. 

DATA SIZE: This field specifies the number of bytes to be reserved for 
local variables of the procedure. 

At the base of the attribute table there may be a section called the jump table. 
Jump tables are used by the P-machine to determine the locations specified 
by jump instructions. Its entries are self-relative pointers to addresses within 
the procedure code. During execution, the JTAB, XJTAB psuedo-register 
points to the PROCEDURE NUMBER field of the attribute table of the currently 
executing procedure. (See Chapter 3 for an explanation of the pseudo- 
registers.) 

All jump instructions include a specified jump offset (n). In the case of short 
forward jumps, the jump table is ignored, and execution jumps by n bytes. In 
the case of backward or long forward jumps, the jump offset specifies a self- 
relative pointer in the jump table located n bytes below the location pointed to 
by the JTAB register. Execution jumps to the byte address pointed to by the 
self-relative pointer. 

Assembly-Language Procedure Attribute Tables 

The format of an attribute table of an assembly-language procedure is very 
different from that of a P-code procedure attribute table. It is illustrated in 
Figure 2-10. 
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Figure 2-10. An Assembly-Unguage Procedure Attribute Table 

The highest word in the attribute table of an assembly-language procedure 
always has a zero in its PROCEDURE NUMBER field. When the interpreter 
encounters a zero in the PROCEDURE NUMBER field as it loads the segment, 
it realizes it must "fix up" references in the procedure code according to 
information contained in the rest of the attribute table. The RELOCSEG 
NUMBER field contains either a zero or a positive number (the significance of 
which is explained below in conjunction with base-relative relocation). In the 
case of intrinsic units without data segments, the number placed in this field is 1 . 
The second highest word of the attribute table is, as in P-code procedure 
attribute tables, the ENTER IC field— a self-relative pointer to the first 
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executable instruction of the procedure . Following this are four relocation 
tables used by the interpreter. From high address to low address, they are 
base-relative, segment-relative, procedure-relative, and interpreter-relative 
relocation tables. 

Relocation Tables 

A relocation table is a sequence of records that contain information 
necessary to relocate any relocatable addresses used by code within the 
procedure. Relocatable addresses are relocated whenever the segment 
containing the procedure is loaded into memory. Only native code procedures 
use relocatable addresses; procedures that contain P-code are completely 
position-independent, and no relocation list is needed. 

The format of all four relocation tables is the same: the highest word of each 
table specifies the number of entries (possibly zero) that follow (at lower disk 
addresses) in the table. The remainder of each table comprises that number of 
one-word self-relative pointers to locations in the procedure code which must 
be "fixed". The locations are fixed by the addition of the appropriate relative 
relocation constant known to the interpreter when the segment is loaded. 

Addresses pointed to by a base-relative relocation table are relocated 
relative to the address contained in the P-machine's BASE, XBASE psuedo- 
register if the RELOCSEG NUMBER field of the procedure's attribute table is 
zero. The BASE, XBASE register is a pointer to the activation record of the 
most recently invoked base procedure (lexical level or - 1 ). Global (lexical 
level 0) variables are accessed by indexing from the value of the BASE 
register. If the RELOCSEG NUMBER field is non-zero, the relocations will be 
relative to the lowest address of the segment whose segment number is 
contained in the RELOCSEG NUMBER field. This is used by assembly 
procedures that are linked with intrinsic units to access the intrinsic unit's data 
segment. .PUBLIC and .PRIVATE are the Assembler directives that generate 
base-relative relocation fields. 

Addresses pointed to by a segment-relative relocation table are relocated 
relative to the lowest address of the segment. The value of the address of the 
lowest byte in the segment is added to each of the addresses pointed to in the 
relocation table. .REF and .DEF are the Assembler directives that generate 
segment-relative relocation fields. 



Addresses pointed to by a procedure-relative relocation table are relocated 
relative to the lowest address of the procedure. The value of the address of 
the lowest byte in the procedure is added to each of the addresses pointed to 
in the relocation table. 

The interpreter-relative relocation fields point to relocatable addresses that 
access Pascal interpreter procedures or variables. Addresses pointed to by 
an interpreter-relative relocation table are relocated relative to a nine-word 
table in the interpreter. See the explanation of the . INTERP directive in the 
Apple III Pascal Program Preparation Tools manual. 

Linker Information 

Following the code part of a segment there may be Linker information. Linker 
information is the portion of a code segment that enables the Linker to resolve 
references of variables, identifiers, and constants between separately 
compiled or assembled code. Segments produced by an Assembler always 
have Linker information. Segments produced by the Compiler have Linker 
information only if they are segments with EXTERNAL procedures or units, or 
user programs that USE regular units. 

The starting location of Linker information is not included in the segment 
dictionary as was the case with the starting location of the interface text and 
code parts; it must be inferred. Linker information starts on the blocic 
boundary following the last block of code for a segment, and grows toward 
higher addresses. The block number of the first record of Linker information 
can be calculated as: 

CODEADDR 4- ((CODELENG -I- 51 1) DIV 512) 

where CODEADDR and CODELENG are the values of fields in the segment 
dictionary. 

Linker information is stored as a sequence of records— one record for each 
indentif ier, constant, or variable which is referenced but not defined in the 
source, as well as records for items defined to be accessible from other 
procedures. 

The following Pascal-like declaration describes one record within Linker 
information: 



LITYPES « (EOFMARK, UNITREF, 6L0BREF, PUBLREF, 
PRIVREF, CONSTREF, 6L0BDEF, PUBLDEF, CONSTOEF, 
EXTPROC, EXTFUNC, SEPPROC, SEPFUNC, SEPPREF, 
SEPFREF); {Linker information types} 

OPFORMAT = (W0RD,BYTE,BI6) ; {label size} 

LCRANGE: 1..MAXLC; {currently MAXINT (32767)} 

PR0CRAN6E: 1..MAXPR0C; {cu r rent I y 1 60 } 

LIENTRY « RECORD 

NAME: PACKED ARRAY[0..73 OF CHAR; 

{name of unit, procedure, or variable 
symbo I } 

CASE LITYPE: LITYPES OF 

6L0BREF, {reference to a g loba I address } 
PUBLREF, {reference to a host program 
variable} 

PRIVREF, (reference to private variables in a 

host activation record} 
CONSTREF, (reference to a global constant} 
UNITREF, (reference to a regular unit} 
SEPPREF, (unused } 
SEPFREF: {unused } 
(FORMAT: OPFORMAT; 
NREFS: INTEGER; 
NWORDS: LCRANGE; 

POINTERLIST: ARR AY C 1 . . ( (NRE FS-1 ) DIV8)+1] 
OF ARRAY C0.. 7] OF INTEGER); 
(segment-relative pointers} 

GLOBDEF: ( g loba I addres s definition} 
(HOMEPROC: PROCRANGE; 
ICOFFSET: LCRANGE) ; 

PUBLDEF: (host program variable definition} 
(BASEOFFSET: LCRANGE); 

CONSTDEF: (host program constant definition} 
(CONSTVAL: INTEGER); 

EXTPROC, (EXTERNAL procedure declaration} 
EXTFUNC, (EXTERNAL function declaration} 
SEPPROC, (separate assembly procedure} 
SEPFUNC: {separate assembly function} 
(SRCPROC: PROCRANGE; 
NPARAMS: INTEGER); 

EOFMARK: (end-of-file mark) 
(NEXTBASELC: LCRANGE; 
PRIVDATASEG: SEGNUMBER); 



END; 
END; 
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Linker Information Fields 

The Linker information types GLOBREF, PUBLREF, PRIVREF, CONSTREF, 
and UNITREF, all have similar fields. The FORMAT field may be BIG, BYTE or 
WORD, and specifies the format of the P-machine operand that refers to the 
entity given by the NAME array (see Chapter 5, Instruction Formats for a 
description of these formats). The NREFS field specifies the number of 
references to this entity in the code segment; there will be an equivalent 
number of entries in the POINTERLIST array. The NWORDS field specifies the 
amount of space, in v/ords, to be allocated for PRIVREF Linker information 
types; the NWORDS field is ignored for all other Linker information types. 

The POINTERLIST array is a list of pointers into the code segment, each of 
which points to a location within the code segment where there is a reference 
to the entity specified by the NAME array. The locations are given as absolute 
byte addresses within the code segment. The POINTERLIST array is 
composed of records of eight words, but only the first ((NREFS- 1 ) MOD 8) + 1 
words of the last record are used. All unused words in each array are 
zeroed. 

Global Address Linker Information Types 

Separate assembly-language procedures and functions can share data 
structures and subroutines by means of the .DEF, .REF, .PROG, and .FUNG 
Assembler directives. These directives cause the Assembler to generate 
information that the Linker uses to resolve external references between 
separate procedures and functions in the same assembly or between 
procedures and functions assembled separately. Each entity referenced by a 
.REF Assembler directive results in a GLOBREF Linker information type entry 
that designates fields to be updated by the Linker. Each entity defined by a 
.DEF, .PROG, or .FUNG Assembler directive results in a GLOBDEF Linker 
information type entry that provides the Linker with the values to fix the .REF 
references. 

The GLOBREF Linker information type is used to link addresses between 
assembled procedures. The FORMAT field is always WORD. The NREFS field 
specifies the number of pointers in the POINTERLIST array (each of which 
points to a different reference). 



The GLOBDEF Linker information type defines the location of an entity in an 
assembled procedure. The HOMEPROC field contains the number of the 
procedure that defines the entity specified by the NAME array. The ICOFFSET 
field specifies the location within the named procedure where the entity is 
defined. The location is given as a byte offset, relative to the start of the 
procedure. There is no POINTERLIST array associated with a GLOBDEF 
Linker information type. 

As a program is linked, the Linker picks up each address defined explicitly by 
.DEF and implicitly by .PROC and .FUNG, and fixes up each reference to it in 
other procedures. The Linker must insert the final segment offset of the 
address in all words pointed to by the POINTERLIST array. 

Host-Communication Linker Information Types 

The Assembler directives .CONST .PUBLIC, and .PRIVATE enable an 
assembly-language procedure or function to share addresses and data space 
with the host program that calls it. Data values and locations are referred to by 
name In both the host program and the called procedure or function. Each 
entity referenced by a .CONST, .PUBLIC, or .PRIVATE Assembler directive 
results in a CONSTREF, PUBLREF, or PRIVREF Linker information type entry, 
respectively, that designates fields to be fixed up by the Linker. Each entity 
defined by a CONSTANT or VARIABLE declaration results in a CONSTDEF or 
PUBLDEF Linker information type entry, respectively, that provides the Linker 
with the values to fix references. As a program is linked, the Linker picks up 
each entity defined by .CONST, .PUBLIC, and .PRIVATE, and fixes up each 
reference to it in other procedures. The Linker must Insert the final segment 
offset of the address In all words pointed to by the POINTERLIST array. 

The PUBLREF Linker information type is used to link global variables in the 
activation record of a host program to assembly-language procedures or 
regular units (activation records are explained in the next chapter). The 
PUBLREF Linker information type results from a .PUBLIC directive in an 
assembly-language procedure or from use of variables declared in the 
INTERFACE of regular units. The NAME array specifies a variable that is 
referenced in the segment, and defined as a global variable in the host 
program. The FORMAT field is WORD for assembly-language procedures, 
and BIG for regular units. The NREFS field specifies the number of pointers in 
the POINTERLIST array (each of which points to a different reference). The 
Linker must add the offset of the referenced identifier to all words pointed to 
by the POINTERLIST array. 
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The PUBLDEF Linker information type declares a global variable in the host 
program. A PUBLDEF Linker information type is generated for each global 
variable in the host program that appears in a VAR declaration. The 
BASEOFFSET field specifies the location of the variable specified by the 
NAME array v^ithin the activation record of the host program that contains it. 
The location is given as a word offset, relative to the start of the data area. 
There is no POINTERLIST array associated with a PUBLDEF Linker 
information type. 

The CONSTREF Linker information type is used to link constants in an 
assembled procedure to a global constant in the host program. The 
CONSTREF Linker information type results from a .CONST directive in an 
assembly-language procedure. The NAME array specifies a constant that is 
referenced in the segment, and defined as a global constant in the host 
program. The FORMAT field is WORD. The NREFS field specifies the number 
of pointers in the POINTERLIST array (each of which points to a different 
reference). The Linker must place the constant value into all locations pointed 
to by the POINTERLIST array. 

The CONSTDEF Linker information type declares a global constant in the host 
program. A CONSTDEF Linker information type is generated for each global 
constant in the host program that appears in a CONSTANT declaration. The 
CONSTVAL field contains the value of the declared constant. There is no 
POINTERLIST array associated with a CONSTDEF Linker information type. 

The PRIVREF Linker information type is used to indicate a reference to 
variables of an assembly-language procedure or regular unit, to be stored in 
the host program's global data area, and yet be inaccessible to the host 
program. The PRIVREF Linker information type results either from a .PRIVATE 
directive in assembly language, or by the use of global variables declared in 
the IMPLEMENTATION of regular units. The FORMAT field is always WORD. 
The N WORDS field specifies the amount of space, in words, to be allocated. 
The NREFS field specifies the number of pointers in the POINTERLIST array. 
The Linker must add the offset of the start of the allocated area within the 
global data area to all words pointed to by the POINTERLIST array. 

The UNITREF Linker information type is used to link references between 
regular units. The NAME array specifies the name of a regular unit that is 
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referenced within another regular unit. The FORMAT field is always BYTE. The 
NREFS field specifies the number of pointers in the POINTERLIST array (each 
of which points to a different reference). The Linker must insert the final 
segment number of the references unit in all locations pointed to by entries in 
the POINTERLIST array. 

Procedure and Function Linker Information Types 

Separate assembly-language procedures and functions are referenced via 
EXTERNAL declarations in the calling segment. The Linker information types 
EXTPROC, EXTFUNC, SEPPROC, and SEPFUNC are used to link 
procedures and functions between segments. Each .PROG or .FUNG entity 
referenced by a PROGEDURE.. .EXTERNAL declaration results in an 
EXTPROG or EXTFUNG Linker information type entry, respectively, that 
designates fields to be fixed up by the Linker. All procedure or function code 
that begins with .PROG or .FUNG results in a SEPPROG or SEPFUNG Linker 
information type entry, respectively, that provides the Linker with the values to 
fix references. As each procedure or function is linked, the Linker picks up 
each procedure number and parameter size declared in the separate 
procedure or function, and transfers it to each external reference of that same 
procedure or function. 

The SRCPROC field specifies the procedure number of the referenced or 
declared procedure. The NPARAMS field specifies the number of words of 
parameters indicated in the .PROG or .FUNG directive. There is no 
POINTERLIST array associated with EXTPROG, EXTFUNG, SEPPROG, or 
SEPFUNG Linker information types. 

Miscellaneous Linker Information Types 

The EOFMARK Linker information type indicates the end of Linker information 
records. Additionally, if the segment is of the host program, the NEXTBASELG 
field indicates the number of words in the host program's global data area. If 
the segment is an intrinsic unit code segment, the PRIVDATASEG field 
contains the segment number of the associated data segment. 
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The P-'Macnine 



The previous chapter discussed the static structure of program codefiles on 
disk and in memory. This chapter discusses the dynamic structure of program 
code as it is being executed in memory. 



Figures 3-1 and 3-2 are diagrams of the Apple Ill's memory when running 
under the Apple Pascal system. These memory maps are specific to the 
Apple III, and do not apply to any other computer. They are provided for your 
information only: a primary tasl< of the Apple Pascal system is to eliminate the 
necessity for the programmer to l<now anything about specific memory 
addresses and use. 



System Memory Use 



The P-Machine 37 



Bank© 




Note: unused areas are 
available for stack/heap 
growth. 



Bank1 



SYSCOM 



program 
stack 



1 



unused 




Bank 2 




$FFFF 

$B7FF 
$A0O0 

$9FFF 



$2000 
$1FFF 
$0000 



Figure 3-1 . Typical Memory Map 
of a 1 28K Apple III Using Apple Pascal 
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Note: The interpreter and device drivers are located in the 
highest bank. If the device drivers require more space 
than is available in the highest bank, they "spill" down into 
the next highest bank, unused areas are available for 
stack/heap growth. 




Figure 3-2. Typical Memory Map of a 256K Apple III 
Using Apple Pascal 



The P^Machine 



The Apple III Pascal pseudo-machine or P-machine, a version of the UCSD 
Pascal P-machine, is the software-generated device that executes P-code as 
its machine language. Every computer operating under a form of UCSD Pascal 
has been programmed to "look like** this common P-machine, or a related 
variant, from the viewpoint of a program being executed. The P-machine has 
an evaluation stack, several registers, and a user memory. The user memory 
contains the program stack, the heap, and extra code space where program 
code can be stored (Figure 3-3). Each of these structures is discussed in 
detail below. 
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Figure 3-3. The P-Machine Model 



Note: In Figure 3-3 pointers to P-code are shown pointing both up and down, 
because P-code may be in either the stack or extra code space. Pointers to 
data are shown pointing down only, because data is stored only in the 
stack/heap space. 
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The P-machine supports: 

• Variable addressing, including strings, byte arrays, packed fields, and 
dynamic variables 

• Logical, integer, real, set, array, and string, top-of-stack arithmetic 
and comparisons 

• Multi-element structure comparisons 

• Branches 

• Procedure and function calls and returns, including overlayable 
procedures 

• Miscellaneous procedures used by system and user programs 

The P-machine uses 1 6-bit words, with two 8-bit bytes per word. Words 
consist of two bytes, of which the lower, even-address byte is least significant 
(Figure 3-4). The least significant bit of a word is bit 0, the most significant is 
bit 15. 

higher, odd address lower, even address 



I I I . 1 I I I 



high byte 

H — I — H 



I I I I I 



low byte 

I I I — hH— + 



bit: 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 

s ^ ^ / 

one word 

Figure 3-4. Relationship of Words and Bytes 



The Evaluation Stack 

In the Apple III, the evaluation stack uses a portion of the relocated 6502 
hardware stack, starting at memory location $1 BFF and growing downward to 
location $1 B00. It is used for passing parameters, returning function values, 
and as an operand source for many P-machine instructions. When an 
instruction is said to push an item, that item is placed on the top of the 
evaluation stack (the evaluation stack grows downward). The evaluation stack 
is extended by loads and is reduced by stores and most arithmetic operations. 



Enhanced Indirect Addressing 



Enhanced indirect addressing is the method used in the Apple III to extend 
its memory addressing beyond 64K bytes. It involves the use of 6502 
indirect-X and indirect-Y addressing modes and depends on hardware 
interaction between the zero page and its corresponding extension page (X- 
page). 

SOS permanently assigns locations $ 1 A00 through $ 1 AFF as the user zero 
page, and the hardware automatically associates locations $ 1 600 through 
$1 6FF as the X-page. Although the zero-page data actually resides at 
locations $ 1 A00 through $1 AFF, instructions that refer to the zero page still 
use address values $00 through $FF. Most Apple III instructions behave 
exactly like their 6502 counterparts, except for indirect-X and indirect-Y 
instructions. Depending on the values in the X-page, these instructions can 
invoke enhanced indirect addressing. 

Consider an indirect-X or Indirect-Y reference through zero-page location n. 
As usual for the 6502, zero-page locations n and n-M are expected to 
contain the operand address (disregarding indexing by X or Y, for the 
moment). Since the zero page is mapped, this operand address is actually 
stored at locations $1 A00+n and $1 A01 +n, with the least-significant byte at 
the lower address. Location $1 601 +n contains the X-byte for this 
addressing operation. The X-byte is interpreted as follows: 

bit: 7 6 5 4 3 2 1 





-f-l- 






E 


1 1 


E 

1 1 


HH 

3 

1 



Bit 7 is the enhanced-addressing bit, or E-bit. If it is zero, normal 6502 
addressing occurs and the rest of the X-byte is ignored. Normal 6502 
addressing means addressing in the 64K address space consisting of a lower 
8K portion followed by the currently switched-in 32 K bank followed by an 
upper 24K portion. 

The normal user should not access the lower 8K or upper 24K, because 
these are occupied by SOS. 
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If bit 7 of the X-byte is one, enhanced indirect addressing occurs. The four-bit 
field B specifies a bank pair consisting of banks B and B + 1 . These two banks 
together make up a continuous 64K address space. The address word stored 
in zero page is taken as the address of a location in this 64K bank pair, 
regardless of which bank is currently switched in. 

Locations $0000 to $00FF (the zeroth page) in each bank pair are actually 
mapped into the current user zero page (locations $1 A00 to $1 AFF). These 
locations should be addressed using ordinary zero-page addressing. 



Registers 

The Apple III P-machine uses eight pseudo-registers, and the hardware stack 
pointer (Figure 3-3). All registers are pointers to word-aligned structures, 
except the IPC register, which is a pointer to byte-aligned structures. 

Because the Apple III uses an enhanced-indirect addressing architecture, 
each psuedo-register (except the SP register), consists of two parts. One part 
is a 1 6-bit pointer on zero page, and the other is a corresponding X-byte on X- 
page. Thus each register (except SP) consists of two components; for 
example, IPC and XI PC. The psuedo-registers are: 

SP: evaluation Stack Pointer. This register contains a pointer to the current 
top of the evaluation stack (one byte below the last byte in use). It is 
actually the Apple III hardware stack pointer. 

IPC, XIPC: Interpreter Program Counter. This register contains the address 
of the next instruction to be executed in the currently-executing 
procedure. 

SEG, XSEG: SEGment pointer. This register points to the highest word of the 
procedure dictionary of the segment to which the currently-executing 
procedure belongs. 

JTAB, XJTAB: Jump TABIe pointer. This register contains a point to the 

highest word of the attribute table in the procedure code of the currently- 
executing procedure. (Attribute tables are explained in Chapter 2.) 




MP, XMP: Markstack Pointer. This register contains a pointer to the MSSTAT 
field, in the markstack of the currently executing procedure. Local 
variables in the activation record of the current procedure are accessed 
by indexing off of the location pointed to by the MP register. (Markstacks 
are explained later in this chapter). 

BASE, XBASE: BASE procedure pointer. This register contains a pointer to 
the MSSTAT field of the activation record of the most recently invoked 
base procedure {lexical level or 1 ). Global (lex level 0) variables are 
accessed by indexing off of the location pointed to by the BASE register. 
(Activation records are explained later in this chapter.) 

STRP, XSTRP: STRing Pointer. This register is a pointer to the first element of 
the linked list of packed arrays of characters and strings on the stack. 
Whenever the P-machine executes an LPA or LSA instruction (see 
Chapter 5), and the literal packed array or string constant contained in 
the instruction is not already on the program stack, the P-machine 
pushes it onto the program stack and links it into the list pointed to by this 
pseudo-register. 

KP, XKP: program stacK Pointer. This register contains a pointer to the 

lowest byte of the lowest word actually in use on the program stack. The 
program stack starts in high addresses of user memory and grows 
downward toward the heap. 

NP, XNP: New Pointer. This register contains a pointer to the current top of 
the heap (one byte above the last byte in use) . The heap starts in low 
addresses of user memory and grows upward toward the program 
stack. It contains all dynamic variables. It is extended by the standard 
Pascal procedure 'new', and is cut back by the standard procedure 
'release'. 

Extra Code Space 

The segments of an executing program may be loaded by the interpreter into 
several different areas of memory. Segments are preferentially loaded in areas 
labeled extra code space in Figures 3- 1 through 3-3, so that the space in the 
stack/heap area is not needlessly consumed. Only when the extra code space 
areas are filled, are segments loaded onto the stack. Segments are never 
loaded into the unused area between the stack and heap. 
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The Program Stack and the Data Heap 

The operating system uses two dynamic structures called the program stack 
and the heap to store memory-resident data of an executing program. The 
program stack and heap reside in the same bank pair. The program stack is 
used to store automatic variables, strings, packed arrays, bookkeeping 
information about procedure and function calls, and code segments if there is 
no available extra code space. The heap is used to store dynamic variables. 

Figure 3-5 is a diagram of the Pascal program stack and heap with four active 
procedures. 



high memory addresses 



SYSeOM 



PASCALSYSTEM 
activation record 



markstack 



MAINPROG 
activatiori record 



markstack 



UNITPROC 
activation record 



markstack 



ALPHAPROCDRE 
activation record 



markstack 



currently unused 



HEAP 



BASE register 



• MP, KP, and STRP registers 



• NP register 



low memory addresses 



Figure 3-5. The Program Stack and Heap With Four Active Procedures 
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SYSCOM 

The operating system and the P-machine exchange information via the system 
communications area (also called SYSCOM) at the bottom (high addresses) of 
the stack. SYSCOM is accessible to both assembly-language procedures in 
the interpreter and (as if it were part of the Pascal system global data) to 
system procedures coded in Pascal. SYSCOM serves as an important 
communication link between these two levels of the system. The fields in 
SYSCOM relevant to communication between the operating system and the 
P-machine are: 

lORSLT: This field contains the error code returned by the last activated or 
terminated I/O operation (see Volume 2 of the Apple III Pascal 
Programmer's Manual for a list of I/O Error messages). 

XEQERR: This field contains the error code of the last execution error (see 
Volume 2 of the Apple III Pascal Programmer's Manual for a list of 
execution error messages). 

BOMBP: This field contains a pointer to the activation record of the procedure 
that caused the execution error. 

BOMBSEG, BOMBPROC, BOMBIPC: These fields contain the segment 
number, procedure number, and IPC value when an execution error 
occurs. 

SYSUNIT: This field contains the Pascal volume number of the device from 
which the operating system was booted (usually the boot disk drive, 
volume 4). 

GDIRP: This field contains a pointer to the most recent Apple II format disk 
directory read in , unless dynamic allocation or deallocation has taken 
place since then (see the MRK, RLS, and NEW instructions, in 
Chapter 5). Disk directories are read into a temporary buffer directly 
above the heap. (Not used for SOS-format directories.) 

Segment Table: The segment table is a record that contains information 
needed by the P-machine to read code segments into memory or to 
allocate space for data segments. 
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THE SEGMENT TABLE 

Every code segment has a name, but when a given segment references 
another during the execution of a program, it refers not to the segment's 
name, but to the segment's number. The interpreter uses the segment number 
as an index into the segment table, which contains an entry for each segment 
in the program (Figure 3-6). The segment table entries are indexed by 
segment number; each entry contains information needed to load the 
segment from the codef lie on disk into memory. The segment table is a 
dynamic structure of SYSCOM, but is somewhat analagous to a segment 
dictionary, in that it is used to locate segments on disk. 

The segment table is located in the higher addresses of the SYSCOM area, at 
the bottom of the program stack. It contains entries for: 

• the segments of the Pascal operating system itself (numbers 0, 2... 6, 
59. ..63) 

• each segment in the segment dictionary of the host program codefile 

• each intrinsic unit code and data segment in library files linked with the 
host program 

No two segments in an executing program can have the same number since 
the numbers are used to index the segment table. The segment table has 
space for up to 64 entries. Since the system can use 1 1 , this means that 
53 entries are left for the program to use. 

Remember that a program codefile contains 1 6 or fewer segments; any 
excess over 1 6 must be in either a program library file, a SYSTEM. LIBRARY 
file, or library files specified in a library name file. 
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segment number 63) 
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entry 1 
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Figure 3-6. The Segment Table 



Activation Records 

When a procedure is called, the'code segment containing that procedure 
code is loaded by the interpreter if it is not already present in memory. An 
activation record for the procedure is built on top of the program stack each 
time the procedure is called (Figure 3-7). Only code segments require 
activation records, data segments do not. The activation record for a 
procedure consists of: 

• the markstack, which contains addressing context information (static 
links), and information on the calling procedure's environment 

• space for storing the value returned by the procedure, if the 
procedure is a function 

• space for parameters passed to the procedure when it is called 

• space for the local variables of the procedure 
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Figure 3-7. An Activation Record 



Space is allocated in the higher addresses of the activation record for variables 
local to the procedure. The variable space is allocated in the reverse order that 
the variables are declared (exception: variables in a variable list are allocated 
space in forward order). For example, the statements 



VAR I, J: INTEGER; 
BOOL: BOOLEAN; 



will cause space in the activation record to be allocated as shown in 
Figure 3-8. 



high memory addresses 



BOOL 



I 

J 



low memory addresses 

Figure 3-8. The Order of Local Variable Allocation 
in an Activation Record 

Space for parameter passing is allocated below the local variable space. If the 
procedure is a function, space is also reserved (below the parameter space) 
for storing the value returned by the function. The order of passed parameters 
is discussed in Chapter 4. A description of the format of variables in activation 
records is given in Chapter 5. 

Local variables in the activation record of an active procedure are accessed by 
indexing off of the location pointed to by the MP, XMP register. Global 
variables in the activation record of an active procedure are accessed by 
indexing off of the location pointed to by the BASE, XBASE register. 

When a procedure is terminated, its activation record is removed from the 
stack. 

Markstacks 

The lower portion of the activation record is called a markstack. When a 
procedure call is made, the current values of the system psuedo-registers that 
characterize the operating environment of the calling procedure are stored in 
the markstack of the called procedure. This allows the system registers to be 
restored to precall conditions when control is returned to the calling 
procedure. 

A procedure call causes the operating environment that existed in the system 
registers just at the time of the procedure call to be stored in the fields of the 
called procedure's markstack in the following manner: 
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System registers Markstack fields 

(MarkStack evaluation Stack 
Pointer) 

(MarkStack Interpreter 
Program Counter) 

(MarkStack X-byte of 
Interpreter Program 
Counter) 

(MarkStack SEGment 
pointer) 

(MarkStack Jump TABIe 
pointer) 

(MarkStack DYNamic link) 

(MarkStack program stacK 
pointer) 

STRP ► MSSTRP (MarkStack STRing Pointer) 

The MSDYN field of a markstack contains a pointer to the MSSTAT field in the 
markstack of the procedure that called the new procedure. The combined 
MSDYN fields of all markstacks form a dynamic chain of links that describe 
the "route" by which the new procedure was called. 

The MSSTAT field of a markstack contains a pointer to the MSSTAT field in the 
most recent markstack of the procedure that is the lexical parent of the called 
procedure. The interpreter "knows" which procedure is the lexical parent, by 
looking up the static ctiain until it encounters a procedure whose lexical level 
is one less than the lexical level of the current procedure. The combined 
MSSTAT fields of a group of markstacks form a static chain of links that 
describe the lexical nesting of the called procedure. 



SP ► MSSP 

IPC ► MSIPC 

Xipc ► MSXIPC 

SEG >- MSSEG 

JTAB ► MSJTAB 

MP ► MSDYN 

KP ► MSKP 



The values of the XSEG and XJTAB registers are not stored on the markstack 
because they are equivalent to XIPC. The XKP, XMP, and NP, XNP registers 
are not stored because they do not change during a procedure call. The 
BASE, XBASE registers are not stored on the markstack because their values 
are related only to base procedure calls. 

After building the new procedure's activation record on the program stack, 
new values for the IPC, XIPC, SEG, XSEG, JTAB, XJTAB, KP, STRP. XSTRP, 
and MP registers, are established. The registers are updated as follows: 

• The SP register is unchanged, and remains pointing to the top of the 
evaluation stack. 

• The KP, XKP register points to the new top of the program stack, just 
beyond the newly-created activation record. 

• The IPC, XIPC register points to the first instruction of the called 
procedure. 

• The SEG, XSEG register points to the procedure dictionary of the 
code segment that contains the called procedure. 

• The JTAB, XJTAB register points to the attribute table of the called 
procedure. 

• The MP, XMP register points to the markstack of the called 
procedure. 

• The STRP, XSTRP register is initialized to NIL (zero). 

• If the called procedure has a lexical level of - 1 or 0, the contents of 
the BASE register are saved on the evaluation stack, and the BASE 
register is set to the value of the MP register. 

Each time a procedure is called, another activation record is added to the 
program stack. Once again the register values and the appropriate static link 
and dynamic link are stored in the new markstack, and the system registers 
are then updated. Note that the SEG register always points to the procedure 
dictionary of the segment that contains the procedure (and not the segment 
that called the procedure). 

Once the code for a procedure has been loaded into memory, each further 
invocation of the same procedure causes only an activation record to be 
added to the program stack (the code is not loaded again). 



When a return from a procedure occurs, the information in the markstack fields 
is transferred to the system registers, and the activation record of the inactive 
procedure is removed from the stack. 

Additional information on procedure calls, and the relation of attribute tables to 
activation records, can be found in the section Procedure and Function Calls 
in Chapter 5. 
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4 

Assembly-Language 
Programming 

Calling Assembly Procedures 
and Functions 



A separate procedure or function is written in assembly language as a PROC 
or .FUNC. The assembled code is assumed to be in a codefile which will be 
linked into the host program before execution. Within the host program, the 
EXTERNAL procedure or function must be declared by a standard 
PROCEDURE or FUNCTION heading followed by the keyword EXTERNAL. 
For example, 

PROCEDURE MAKESCREEN (INDEX: INTEGER); EXTERNAL; 

declares the procedure MAKESCREEN as an EXTERNAL assembly-language 
procedure, with one parameter of type integer. 

Calls to EXTERNAL procedures use standard Pascal syntax, and the Compiler 
checks that each call agrees in type and number of parameters with the 
declaration for that procedure. It is the programmer's responsibility to ensure 
that the assembly-language procedure is compatible with the EXTERNAL 
declaration of the host program. The Linker checks only that the number of 
words of parameters in the host program's EXTERNAL declaration and in the 
separate procedure's .PROC or .FUNC declaration are the same. 



Variable parameters in EXTERNAL procedures and functions can be 




declared without any type. 



Passing Parameters 
to Assembly Procedures 



When the host program executes a call to an EXTERNAL procedure or 
function, the parameters to be passed are pushed onto the evaluation stack in 
the order they are encountered in the host program's calling statement: the 
first parameter is pushed onto the stack (high byte first), then the second 
parameter, and so on . When all the parameters have been passed , the host 
program's return address is pushed onto the stack (high byte first) 
(Figure 4-1 ). In addition, if the procedure is a function, the host program 
pushes two words (four bytes) of zeros onto the evaluation stack after any 
parameters are pushed and before the return address is pushed. 



high memory addresses 



old data byte 



first param high byte 
first param low byte 



last param high byte 
last param low byte 



return addr high byte 

top of stack as 

the assembly procedure ^ return addr low byte 

is called i 

low memory addresses 



Figure 4-1 . Order of Parameters on the Stack 



The passed parameters are available on the stack In reverse order: the last 
one passed is at the top of the stack. For example, the function call 

FUNCTION MULT3(I, J, K:INTE6ER); EXTERNAL; 

causes I to be pushed onto the stack first, then J, then K, then four unused 
bytes, and finally the return address (Figure 4-2). Then the function is called. 

high memory addresses 



I 



J 
K 

4 unused bytes 
return address 



low memory addresses 

Figure 4-2. The Order of Parameters on the Stack Just Prior to 
Execution of a Function 

Long integers and sets are passed as the number of words used in the host 
program. Again, each word is pushed onto the stack high byte first. After a 
long integer or set, a word indicating the number of words passed is pushed 
onto the stack. Strings, records, arrays, and VAR parameters are passed by 
address, high byte first. Recall that the host program's EXTERNAL declaration 
may declare a VAR parameter without a type, which allows a parameter of 
indeterminate size to be passed by address. Below are listed the various ways 
that different parameter types are represented on the stack. 



growth 
of 
the 
stack 



Assembly-Language Programming 57 



Passing Mode 

Pass by refer- 
ence (VAR) 



Pass by value 



Parameter Type 

all types 



integer, subrange, 
enumerated type 

real 



set 



long integer 



Representation on Staci( 

A 2-byte pointer to the 
value, with the high byte 
pushed first 

A 2-byte value, with the high 
byte pushed first 

A 4-byte value, with the high 
byte pushed first 

1 to 32 words (representing 
the set value) are pushed 
first. Then a word specifying 
the number of words in the 
set is pushed (high byte 
first). 

1 to 9 words (representing 
the long integer value) are 
pushed first. Then a word 
specifying the number of 
words in the long integer 
value is pushed (high byte 
first). 



string, 

record, 

array 



A 2-byte pointer to the value, 
with the high byte pushed 
first 
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Assembly-Language Procedures 

The TIMES2 function in the assembly-language example below uses 
parameter-passing by value. 

;sample assembly language for 
jFUNCTION TIMES2(DATA: INTEGER) : 
; INTEGER; 



.FUNC TIMES2,1 ;one word of parameters 

RETURN .EQU ;temp store return address 

PLA ;save host segment return address 

STA RETURN 

PLA 

STA RETURN+1 

PLA ;discard four unused bytes 

PLA ;(only necessary for functions) 

PLA 

PLA 

PLA ; least significantbyte <lsb) of data 

ASL A ;times 2 

TAX ;save in X 

PLA ;most significant byte (msb) of data 

ROL A ;times2,withcarry 

PHA ;move msb to evaluation stack 

TXA ;restore Isb to accumulator 

PHA ;movelsbtoevaluationstack 

LDA RETURN + 1 ; res tore host segment return address 

PHA 

LDA RETURN 
PHA 

R T S ;return to calling segment 
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The function first removes the return address from the stack and saves it in the 
location RETURN. After discarding the four unused bytes added to the stack 
because the host program was calling a function, the function then picks up 
the data v^ord, one byte at a time. When it is finished, the function pushes the 
result back onto the stack, followed by the return address. 

The SETZERO procedure in the assembly-language example below uses 
parameter passing by reference. 

;sample assembly language for 
;PROCEDURE SETZERO (VAR IrlNTEGER); 
; EXTERNAL; 



.PROC SETZERO, 1 

RETURN .EQU ;temp store return address 

DATADR .EQU 0E0 

PLA ;save host segment return address 

STA RETURN 

PLA 

STA RETURN+1 

PLA ;Putaddressofparameter 

STA DATADR ; I i nt o I oca t i ons $0E0-0E1 

PLA 

STA DATADR-^I ;$16E1 is already set to 

; Pascal data area x-value 

LDA #0 ; Zero to A 

TAY ; . . .and Y 

STA ©DATADR, Y ;Store in word pointed 

INY ; to by DATADR 

STA @DATADR,Y 

LDA RETURN+1 jrestore host segment return 

P H A ; a d d r e s s 

LDA RETURN 
PHA 

RTS ;returntohostsegment 



Returning From 
Assembly Procedures 



Procedures and functions remove all parameters from the stack before 
returning. When a procedure terminates, it pushes the return address back 
onto the stack, and executes an RTS to the calling segment. When a function 
terminates, it pushes the return value (a scalar, real, or pointer, maximum two 
words) and the return address back onto the stack, and then executes an RTS 
to the calling segment. 

Temporary and Semipermanent Storage 



When you write assembly-language procedures for the Apple III, you must 
respect the SOS and Pascal conventions concerning register use and calling 
sequences. All of the 6502 registers are available, and zero-page 
locations $0 through $35 are available for storing temporary variables. 
However, the Apple III Pascal System also uses these locations as 
temporaries, so you should not expect data to remain there from one 
procedure execution to the next. You can save variables in nonzero page 
memory by using the .BYTE or .WORD directives to reserve space in your 
assembly-language procedure. 

Accessing Pascal Data Space 



To access stack/heap space, an assembly-language procedure must perform 
indirect-X or indirect-Y addressing using an appropriate X-byte value. For 
example, if the stack/heap is in banks 1 and 2, the appropriate X-byte is $81 
(the high-order bit set to one enables enhanced indirect addressing and the 
low-order bits specify the bank pair 1-2). 

Since the Pascal subprocedure linkage mechanism only passes two-byte 
addresses (the X-byte is excluded), it is the programmer's responsibility to 
make sure the X-byte is properly set. The Pascal system presets locations 
$1 6E1 , $1 6E3, $1 6E5, and so on through $1 6EF to the X-byte value for 
Pascal data space at boot time. Thus, assembly-language procedures can 
copy parameter addresses into locations $E0-$E1 , $E2-$E3, and so on 
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through $EE-$EF and perform indirect-X or indirect-Y addressing with these 
zero-page addresses to access the parameters in Pascal data space. 

The following example shows how to access .PUBLIC data by using this 
approach: 



;sample assembly language for 
.•PROCEDURE TEST; 



. P RO C 


TEST 




. EQU 







. EQU 


0E0 


;first pseudo- register 


.PUBLIC 


DATA 


;data belongs to the host 


P L A 




*Cjkv/A K^c^* CAnmAn4* i>A4'iiiKf^ a/4/^r«Ae>c^ 

f t> a V x: iiubk aeymcnt rcLurn auuress 


ST A 


RETURN 




P LA 






STA 


RETURN+1 




L U n 


M U M 1 A 


;fnove address into pseudo~ 


STA 


DATR 


; r e 9 i s t e r 


LDA 


ADATA+1 




STA 


DATR+1 




LOY 


#0 




LDA 


<@»DATR, Y 


;load the DATA into the accumulator 


LDY 


#1 


;if DATA = PACKED ARRAYC0..203 OF 


LDA 


@DATR , Y 


;CHAR. this loads DATAC103 


LDA 


RETURN+1 


jrestore host segment return address 


PHA 






LDA 


RETURN 




PHA 






RTS 




; return to host segment 


.WORD 


DATA 


;thehost*saddress of DATA 



Enhanced indirect addressing also occurs in the assembly-language example 
below. The INCARRAY procedure pulls the return address from the stack and 
saves it at location RETURN. It then pulls the address of the array from the 
stack and stores it in the pseudo-register at location $00E0. After getting the 
remaining parameters from the stack, the procedure uses enhanced indirect 
addressing (indirect-Y addressing) to modify the array data where it is stored 
in memory. 
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;safnple assembly language for 

; PROCEDURE I N C ARR AY ( S I ZE : I NTE6ER ; 

; VAR DATA: LIST) ; 



.PROC INCARRAY,2 ;2 words of parameters 

RETURN .EQU ;temp store return address 

SIZE .EQU 2 ;temp store SIZE 

PSUEDO .EQU E ; pseudo-register 

PLA ;save host segment return address 

STA RETURN 

PLA 

STA RETURN+1 

PLA ;lsb of array address 

STA PSEUDO 

PLA ;msb of array address 

STA PSEUDO+1 

PLA ; I sb of S I ZE pa r ame t er 

STA SIZE 

PLA ;msb of SIZE discard 

LDY #0 ; 1 ni 1 1 a I i ze a r ray i ndex 

ALOOP CLC ;clear for add 

LOA <g)PSEUDO,Y ;load byte array 

ADC #1 ; increment 

STA @PSEUOO,Y ;store incremented array byte 

INY ;increment array index 

CPY SIZE ?test vs. array SIZE 

BCC ALOOP ;do while less than 

LOA RETURN+1 ; restore host segment return address 

PHA 

LDA RETURN 
PHA 

RTS ;return to host segment 



All parameters that are passed by address must be accessed by enhanced 
indirect addressing. 
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5 

The P'Machine Instruction Set 



Instruction Formats 



Instructions for the P-machine consist of one or two bytes, followed by zero to 
four parameters. Most parameters specify one word of information. There are 
five basic types of parameters: 

UB: Unsigned Byte. Represents a non-negative integer less than 256. The 
high-order byte of the parameter is implicitly zero. 

SB: Signed Byte. Represents an integer from - 1 28 to 1 27, in two's- 

complement form. The high-order byte is a sign extension of bit 7 of the 
low order byte. 

DB: Don't-care Byte. Represents a non-negative integer less than 1 28, 
thus it can be treated as SB or UB. 

B: Big. This parameter is one byte long when used to represent values in 
the range through 127, and is two bytes long when used to represent 
values in the range 1 28 through 32767. If the value represented is in 
the range through 1 27, the high-order byte of the parameter is 
implicitly zero. If the value represented is in the range 1 28 through 
32767, bit 7 of the first byte is cleared and the first byte is used as the 
high order byte of the parameter. The second byte is used as the low- 
order byte. 

W: Word. A two-byte parameter, low byte first. Represents values in the 
range -32768 through 32767. 

Any exceptions to these formats are noted in the descriptions of the individual 
instructions. 




Operand Formats 



Although an element of a structure in memory may be as small as one bit (as in 
a packed array of boolean), variables to be operated on by the P-machine are 
always unpacked into full words. All top-of-stack (tos) operations expect their 
operands to occupy at least one word on the evaluation stack. 

Formats of Variables on the Stack 

Variables are stored in activation records and on the evaluation stack in the 
manner described below. 

BOOLEAN: One word. Bit indicates the value (0=FALSE, 1 =TRUE), and 
this is the only information used by boolean compahsons. However, the 
boolean operators LAND, LOR, and LNOT operate on all 1 6 bits, in a 
bitwise manner. 

INTEGER: One word, two's complement notation, capable of representing 
values in the range --32768..32767. 

LONG INTEGER: 3. . 1 1 words. A variable declared as INTEGER[n] is 
allocated ((n+3) DIV 4) + 2 words of memory space. Regardless of 
the value of a long integer, its actual size remains the same as its 
allocated size. Each decimal digit of a long integer is stored as four bits of 
binary-coded decimal. The format of long integers on the stack is as 
follows: 



word (tos): 



contains the allocated length, in words. 



word 1 (tos 



low byte contains the sign (all zeros = positive, 
all ones — negative); high byte not used. 



word 2 (tos 



2): 



four least significant decimal digits. The low 
byte contains the two more significant decimal 
digits (BCD). The high byte contains the two 
less significant digits. 
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word n (tos-n): four most significant decimal digits. The low 

byte contains the two more significant decimal 
digits (BCD). The high byte contains the two 
less significant digits. 

The format of long integers in activation records is as follows: word is 
not stored; word 1 is the lowest word in memory; word n is the highest 
word in memory. 

SCALAR (user-defined): One word, in range ©..32767. 

CHAR: One word, with the low byte containing a character. The internal 
character set is exfended ASCII, with 0.. 1 27 representing the standard 
ASCII set, and 1 28.. 255 representing user-defined characters. 

REAL: Two words , whose format is defined by the Proposed Standard for 
Binary Floating-Point Arithmetic, IEEE Task P754, and described in the 
Apple III Pascal Programmer's Manual, Volume 2. In general, the format 
for 32-bit real numbers is as follows: 

Bit Item Contained In 

0..15 mantissa tos 

15.. 22 mantissa 

23.. 30 exponent tos-1 

31 sign 

POINTER: One or three words, depending on the type of pointer. Pascal 
pointers (internal word pointers) consist of one word that contains a 
word address (the address of the low byte of the word). Internal byte 
pointers consist of one word that contains a byte address. Internal 
packed field pointers consist of three words: 



word (tos): right bit number of field 
word 1 (tos-1): field width (in bits) 

word 2 (tos -2): word pointer to the word that contains the field 
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SET: 0..31 words in an activation record, 1 ..32 words on the evaluation 
stack. Sets are implemented as bit vectors, always with a lower index of 
zero. A set variable declared as SET OF m. .n is allocated 
{n+ 1 5) DIV 1 6 words of memory space. All words allocated in an 
activation record for a set contain valid information (the set's actual size 
agrees with its allocated size). 

A set on the evaluation stack is represented by a word (tos) specifying 
the length of the set, followed by that number of words of information. 
The set may be padded with extra words (to compare it with another set 
of different size, say), the length word changed to indicate the number of 
words in the structure when padded. Before being stored back in an 
activation record, a set must be forced back to the size allocated to it, by 
issuing an AD J instruction. 

RECORDS and ARRAYS: Any number of words. Arrays are stored in 
forward order, with higher-indexed array elements appearing in 
higher-numbered memory locations. Only the address of the 
record or array is loaded onto the evaluation stack, never the 
structure itself. Packed arrays must have an integral number of 
elements in each word, as there is no packing across word 
boundaries (it is acceptable to have unused bits in each word). The 
first element in each word has bit as its low-order bit. 

STRINGS: 1 . . 1 28 words. Strings are a flexible version of packed 
arrays of characters. A STRING[n] declaration occupies 
(n DIV 2)-f 1 words of memory space. Byte of a string is the 
current length of the string, and bytes 1 ..length(string) contain 
valid characters. 

Format of Constants in P-Code 

CONSTANTS: Constant scalars, sets, and strings may be imbedded in the 
instruction stream, in which case they have special formats. 

• All scalars (excluding reals) greater than 1 27 are represented by two 
bytes, high byte first. 
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• All string literals occupy length(literal) + 1 bytes of memory space, 
and are word-aligned. The first byte is the length, the rest are the 
actual characters. This format applies even if the literal should be 
interpreted as a packed array of characters. 

• All reals, sets, and long integers are word-aligned and in REVERSE 
word order, that is, the higher-order bits of the real or set are in lower- 
numbered memory locations. 



Each operand on the evaluation stack (for example, tos or tos- 1 ), can contain 
from one byte to 266 bytes, depending on its type and value. Unless 
specifically noted to the contrary, operands used by an instruction are popped 
off the evaluation stack (removed from the stack and not returned) as they are 
used. 

In the descriptions of the various P-machine instructions the parameters are 
given as UB , SB , DB , B , or W . The term tos means the operand on the top 
of the evaluation stack, tos - 1 is the next operand, and so on. The columns of 
information in the various instruction descriptions have the following meanings: 

Column Column Column Column 



Conventions and Notation 



1 



2 



op-code 
mnemonic 



decimal 
op-code 



instruction 
parameters 



full name and operation 
of the instruction 



One- Word Loads and Stores 



Constant 



SLDC 
SLDC 




1 



Short load one-word constant. For an 
instruction SLDC_x , push the 
opcode, X , with the high byte 



SLDC 



127 



127 



zero. That is, push an integer with 



the value x. 
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LDCN 



159 



Load constant NIL. Push O. 



LDCI 



199 



W 



Load one-word constant. Push W. 



Local 

SLDI — 1 216 Short load local word . For an Instruction 

SLDL_2 217 SLDL-x .fetch the word with 

: : : offset x in the data area of the 

SLDL- 16 231 executing procedure's activation 

record and push it. 

LDL 202 B Load local word. Fetch the word with 

offset B in the data area of the 
executing procedure's activation 
record and push it. 

LLA 198 B Load local address. Fetch the address 

of the word with offset B in the 
data area in the executing 
procedure's activation record and 
push it. 

STL 204 B Store local word. Store tos into word 

with offset B in the data area of 
the executing procedure's 
activation record. 



Global 

SLDO-1 232 Short load global word. For an 

SLD_2 233 instruction SLDO-x .fetch the 

: : : wordwithoffset x in the data area 

SLDO -16 247 of the activation record of the base 

procedure and push it. 
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LDO 169 B Load global word. Fetch the word with 

offset B in the data area of the 
activation record of the base 
procedure and push it. 

LAO 1 65 B Load global address. Fetch the address 

of the word with offset B in the 
data area of the activation record 
of the base procedure and push it. 

SRO 171 B Store global word. Store tos into the 

word with offset B in the data 
area of the activation record of the 
base procedure. 

Intermediate 

LOD 182 DB.B Load intermediate word. Fetch the word 

with offset B in the activation 
record found by traversing DB 
links in the static chain, and 
push it. 

LDA 178 DB,B Load intermediate address. Fetch 

address of the word with offset B 
in the activation record found by 
traversing DB links in the static 
chain, and push it. 

STR 184 DB,B Storeintermediate word. Store tos into 

the word with offset B in the 
activation record found by 
traversing DB links in the static 
chain. 
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Indirect 

SIND_0 248 Load indirectword. Fetch the word 

pointed to by tos and push it (this 
is a special case of SIND-x , 
described below). 

Short index and load word. For an 
instruction SIND-x . index the 
word pointer tos by x words, 
and push the word pointed to by 
the result. 

IND 1 63 B Static index and load word. Index the 

word pointer tos by B words, 
and push the word pointed to by 
the result. 

STO 154 Store indirect word. Store tos into the 

word pointed to by tos-1 . 

Extended 

LDE 157 UB,B Loadextended word. Fetch the word 

with offset B in the data segment 
number UB (of an intrinsic unit) 
and push it. 

LAE 167 UB,B Load extended address. Fetch the 

address of the word with offset B 
in the data segment number UB 
(of an intrinsic unit), and push it. 

STE 209 UB,B Storeextended word. Store tos into 

the word with offset B in the data 
segment number UB (of an 
intrinsic unit). 



SIND_1 249 
SIND_2 250 

SIND_7 255 
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Multiple-Word Loads and Stores (Sets and Reals) 

LDC 179 UB,<data> Load multiple-word constant. 

Fetch the word-aligned <data> of 
UB words in reverse word order, 
and push the data. 



LDM 1 88 UB 



STM 1 89 UB 



Load multiple words. Fetch UB words 
of word-aligned data in reverse 
order, whose beginning is pointed 
to by tos , and push the block. 

Store multiple words. Transfer UB 
words of word-aligned data in 
reverse order, whose beginnings 
pointed to by tos , to the location 
block pointed to by tos-1 . 



Byte Array Handling 

LDB 1 90 

STB 191 



Load byte. Index the byte pointer 

tos-1 by the integer index tos , 
and push the byte (after zeroing 
high byte) pointed to by the 
resulting byte pointer. 

Store byte. Index the byte pointer 
tos - 2 by the integer index 
tos-1 , and push the byte tos 
into the location pointed to by the 
resulting byte pointer. 
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String Handling 

LSA 1 66 



UB, <chars> Load constant string address. 

Push a word pointer to the 
constant character string 
UB, < chars > onto the evaluation 
stack. As the constant string is 
contained in the code segment, 
and may not be in the stack/heap 
space, a copy of the string is 
pushed onto the program stack. If 
this string has not previously been 
pushed onto the stack during the 
currently-active procedure, copy 
UB< chars) onto the program 
stack (add one space to the end of 
thestringif UB<chars> isan 
even number of characters); push 
a 1 6-bit integer onto the program 
stack that points to the first byte of 
the string in the procedure code ; 
push a 1 6-bit linkage pointer onto 
the program stack that points to 
the string or packed array most 
recently pushed onto the program 
stack (the linkage pointer is if no 
other string or packed arr-ay has 
yet been pushed ontothe^stack); 
push a pointer onto the evaluation 
stack that points to the string 
length byte UB on theprogram 
stack. 
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SAS 1 70 UB 



IXS 156 



If UB< chars) has been pushed 
onto the stack during the 
currently-active procedure, push a 
pointer onto the evaluation stack 
that points to the string length byte 
UB on the program stack. The 
contents of the program stack are 
not changed, which prevents 
needless, possibly stack- 
overflowing entries. 

In either case, advance the IPC 
register past the original copy of 
the string in the code space. 

String assign, tos is either a source 
byte pointer or a character. 
(Characters always have a high 
byte of zero, while pointers never 
do.) tos - 1 is a destination byte 
pointer. UB is the declared size of 
the destination string. If the 
declared size is less than the 
current size of the source string, 
give an execution error; otherwise 
transfer all bytes of source 
containing valid information to the 
destination string. 

Index string array, tos-1 is a byte 
pointer to a string, tos is an index 
into the string. Check to see that 
the index is in the range 1 . .current 
string length. If so, continue 
execution; if not, give an 
execution error. 
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Record and Array Handling 

MOV 168 B Move words. Transfer a source block of 

B words, pointed to by byte 
pointer tos , to a similar 
destination block pointed to by 
byte pointer tos-1 . 

INC 1 62 B Increment field pointer. Index the word 

pointer tos by B words and 
push the resultant word pointer. 

IXA 164 B Index array, tos is an integer index, 

tos - 1 is the array base word 
pointer, and B is the size (in 
words) of an array element. 
Compute a word pointer (tos-1 ) 
+ ( B * tos ) to the indexed 
element and push the pointer. 

IXP 192 UB1,UB2 Index packed array, tos is an 

integer index, tos-1 is the array 
base word pointer. UB1 is the 
number of elements per word, and 
UB2 is the field width (in bits). 
Compute a packed field pointer to 
the indexed field and push the 
resulting pointer. 

LPA 208 UB,<chars> Load a packed array. Push a word 

pointer to the packed array 
< chars) onto the evaluation 
stack. As the packed array is 
contained in the code segment, 
and may not be in the stack/heap 
space, a copy of the array is 
pushed onto the program stack. If 
this packed array has not 
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previously been pushed onto the 
stack during the currently-active 
procedure, copy < chars) onto 
the program stack (add one space 
to the end of the packed array if 
< chars > has an odd number of 
characters); push a 1 6-bit integer 
onto the program stack that points 
to the first byte of the packed array 
in the procedure code; push a 
1 6-bit linkage pointer onto the 
program stack that points to the 
string or packed array most 
recently pushed onto the program 
stack (the linkage pointer is if no 
other string or packed array has 
yet been pushed onto the stack); 
push a pointer onto the evaluation 
stack that points to the first byte of 
the packed array on the program 
stack. 

If the same packed array has been 
pushed onto the stack during the 
currently-active procedure, push a 
pointer onto the evaluation stack 
that points to the first byte of the 
packed array on the program 
stack. The contents of the 
program stack are not changed, 
which prevents needless, 
possibly stack-overflowing 
entries. 

In either case, advance the IPC 
register past the original copy of 
the string in the code space. 



LDP 186 Load a packed field. Fetch the field 

indicated by the packed field 
pointer tos , and push it. 

STP 1 87 Store into a packed field. Store the data 

tos into the field indicated by the 
packed field pointer tos-1 . 



Dynamic Variable Allocation 

Note that the NP, XNP register points to the current top of the heap (one byte 
beyond the last byte in use). GDIRP is a SYSCOM field that points to the top of 
a temporary directory buffer above the heap. 

NEW 158 1 New variable allocation, tos is the size 

(in words) to allocate for the 
variable, and tos-1 is a word 
pointer to a pointer variable . If the 
GDIRP field is non-NIL, set GDIRP 
to NIL. Store the NP register into 
the word pointed to by tos-1 , 
and increment the NP register by 
tos words. 

MRK 158 31 Mark heap. Set the GDIRP field to NIL, 

then store the NP register into the 
word indicated by the word pointer 
tos . 

RLS 158 32 Release heap. Set the GDIRP field to 

NIL, then store the word indicated 
by the word pointer tos into the 
NP register. 



Top-of-Stack Arithmetic 



Integers 

Note: Overflows do not cause an execution error; they are ignored and the 
results are undefined. 

ABI 128 Absolute value of integer. Push the 

absolute value of the integer tos . 
The result is undefined if tos is 
initially -32768. 

ADI 130 Add integers. Add tos and tos-1 , 

and push the resulting sum. 

NGI 1 45 Negate integer. Push the two's 

complement of tos . The result is 
undefined if tos is initially 
-32768. 

SBI 149 Subtract integers. Subtract tos from 

tos-1 , and push the resulting 
difference. 

MPI 143 Multiply integers. Multiply tos and 

tos- 1 , and push the resulting 
product. 

SQI 1 62 Square integer. Square tos , and push 

the result. 

DVI 134 Divide integers. Divide tos— 1 by tos 

and push the resulting integer 
quotient (any remainder is 
discarded). Division by zero 
causes an execution error. 
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MODI 



CHK 



142 



136 



Modulo Integers. Divide tos— 1 by tos 
and push the resulting remainder. 

Check against subrange bounds. Insure 
that tos-1 <= tos-2 <= tos , 
leaving tos-2 on the stack. If 
conditions are not satisfied, give 
an execution error. 



EQUI 


195 


tos-1 = 


tos . 


NEQI 


203 


tos-1 <> 


tos . 


LEQI 


200 


tos-1 < = 


tos . 


LESI 


201 


tos-1 < 


tos . 


GEQI 


196 


tos-1 > = 


tos . 


GRTI 


197 


tos-1 > 


tos . 






Integer comparisons. Compare tes- 






te tos and push the result, TRUE or 



FALSE. 



Non-Integer Comparisons 

The next six instructions are non-specific non-Integer comparisons. 
Comparisons using specific values of UB are given in later sections. 



EQU 


175 


UB 


tos-1 




tos . 


NEQ 


183 


UB 


tos-1 


<> 


tos . 


LEQ 


180 


UB 


tos-1 


<- 


tos . 


LES 


181 


UB 


tos-1 


< 


tos . 


GEO 


176 


UB 


tos-1 


> = 


tos . 
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GRT 177 UB tos-1 > tos . 

Compare tos-1 to tos , and push the 
result, TRUE or FALSE. The type of 
comparison is specified by UB : 



Contents of 


Value of UB 


tos - 1 & tos 


for Comparison 


reals 


2 


strings 


4 


booleans 


6 


sets 


8 


byte arrays 


10 


words 


12 



Reals 

FLT 138 Float top-of-stack. Convert the integer 

tos to a floating point number, and 
push the result. 

FLO 137 Float next to top-of-stack. tos is a real, 

tos-1 is an integer. Convert 
tos-1 to a real number, and push 
the result. 

TNC 158 22 Truncate real. Truncate (as defined in 

Jensen and Wirth*) the real tos 
and convert it to an integer, and 
push the result. 

RND 158 23 Round real. Round (as defined in 

Jensen and Wirth * ) the real tos , 
then truncate and convert to an 
integer, and finally push the result. 

ABR 129 Absolutevalueof real. Push the 

absolute value of the real tos . 



ADR 



131 



Add reals. Add tos and tos-1 ,and 
push the resulting sum. 



NGR 



146 



Negate real. Negate the real tos , and 
push the result. 



SBR 



150 



Subtract reals. Subtract tos from 
tos— 1 , and push the resulting 
difference. 



MPR 



144 



SQR 



DVR 



POT 



EQUREAL 

NEQREAL 

LEQREAL 

LESREAL 

GEQREAL 

GTRREAL 



153 



135 



158 35 



175 
183 
180 
181 
176 
177 



2 
2 
2 
2 
2 
2 



Multiply reals. Multiply tos and 

tos-1 , and push the resulting 
product. 

Square real. Square tos , and push the 
result. 

Divide reals. Divide tos-1 by tos, and 
push the resulting quotient. 

Powerof ten. If the integer tos is in the 
range < = tos < = 38 , push 
the real value 1 0Atos . If the 
integer tos is not in this range, 
give an execution error. 



tos-1 
tos-1 
tos-1 
tos-1 
tos-1 
tos-1 



<> 
< = 
< 

> = 
> 



tos 
tos 
tos 
tos 
tos 
tos 



Real comparisons. Compare the real 
tos-1 to the real tos , and push 
the result, TRUE or FALSE. 



* Kathleen Jensen and Niklaus Wirth: Pascal User's Manual and Report, 
2nd ed.(New York: Springer- Verlag, 1978), p. 13 
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Strings 

EQUSTR 
NEQSTR 
LEQSTR 
LESSTR 
GEQSTR 
GRTSTR 



175 
183 
180 
181 
176 
177 



4 
4 
4 
4 
4 
4 



tos-1 
tos-1 
tos-1 
tos-1 
tos-1 
tos-1 



<> 

< 

> 



I 
I 



tos . 
tos . 
tos . 
tos . 
tos . 
tos 



string comparisons. Find the string 
pointed to by word pointer 
tos-1 , compare it alphabetically 
to the string pointed to by word 
pointer tos , and push the result, 
TRUE or FALSE. 



Logical 

LAND 



LOR 



LNOT 



132 



141 



147 



Logical AND. Push the result of 

tos - 1 AND tos . This is a bitwise 
AND of two 1 6-bit words. 

Logical OR. Push the result of 

tos-1 OR tos . This is a bitwise 
OR of two 1 6-bit words. 

Logical NOT. Push the one's 

complement of tos . This is a 
bitwise negation of one 1 6-bit 
word. 



EQUBOOL 

NEQBOOL 

LEQBOOL 

LESBOOL 

GEQBOOL 

GRTBOOL 



175 
183 
180 
181 
176 
177 



6 
6 
6 
6 
6 
6 



tos-1 
tos-1 
tos-1 
tos-1 
tos-1 
tos-1 



tos . 
tos . 
tos . 
tos . 
tos . 
tos . 



Boolean comparisons. Compare bit of 
tos - 1 to bit of tos and push 
the result, TRUE or FALSE. 
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Sets 

ADJ 



160 



SGS 



151 



SRS 



148 



INN 



139 



UNI 



INT 



156 



140 



DIF 



133 



UB Adjust set. Force the set tos to occupy 
UB words, either by expansion 
(putting zeros "between" tos and 
tos-1 ) or by compression 
(chopping high words off the set), 
discard the length word, and push 
the resulting set. 

Build a one member set. If the integer 
tos is in the range 
< = tos < = 51 1 , push the set 
[tos] . If not, give an execution 
error. 

Build a subrange set. If the integer tos 
is in the range < = tos < = 51 1 , 
and the integer tos-1 is in the 
same range, push the set 
[tos-1 ..tos] (push the set [ ]if 
tos-1 > tos ). If either integer 
exceeds the range, give an 
execution error. 

Set membership. If integer tos-1 is in 
set tos , push TRUE. If not, push 
FALSE. 

Set union. Push the union of sets tos 
and tos-1 . ( tos OR tos-1 ) 

Set intersection. Push the intersection 
of sets tos and tos-1 . 
(tos AND tos-1 ) 

Set difference. Push the difference of 
sets tos-1 and tos . 
(tos-1 AND NOT tos ). 
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EQUPOWR 175 8 

NEQPOWR 183 8 

LEQPOWR 180 8 

GEQPOWR 176 8 



tos-1 = tos . 

tos-1 <> tos . 

tos-1 <= (is a subset of) tos. 

tos-1 >= (is a superset of) tos. 

Set comparisons. Compare set tos - 1 
to the set tos , and push the 
result, TRUE or FALSE. 



Byte Arrays 



EQUBYT 

NEQBYT 

LEQBYT 

LESBYT 

GEQBYT 

GRTBYT 



175 
183 
180 
181 
176 
177 



10, B 
10, B 
10, B 
10, B 
10, B 
10, B 



tos-1 
tos-1 
tos-1 
tos-1 
tos-1 
tos-1 



tos . 
tos . 
tos . 
tos . 
tos . 
tos . 



Byte array comparisons. Compare byte 
array tos-1 to byte array tos , 
and push the result, TRUE or 
FALSE. Note: < = ,<,> = , and) 
must be used with packed arrays 
of characters only. B specifies the 
number of bytes to compare. 



Records and Word Array Comparisons 

EQUWORD 175 12, B tos-1 = tos. 

NEQWORD 183 12, B tos-1 <> tos. 

Word or multiword structure 

comparisons. Compare word 
structure tos-1 to word 
structure tos , and push the result, 
TRUE or FALSE. B gives the 
number of bytes to compare. 
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Jumps 

The JTAB, XJTAB register points to the highest word of the attribute table in 
the currently-executing procedure. The IPC, XIPC register points to the next 
instruction to be executed in the currently-activating procedure. 

UJP 185 SB Unconditional jump. SB is a jump offset. 

If this offset is non-negative (a 
jump less than 1 28 bytes 
forward), it is simply added to the 
IPC register. (A value of zero for 
the jump off set will mal^e any jump 
atwo-byteNOP.)lf SB is 
negative (a jump bacl<ward or 
more than 1 27 bytes forward), 
then SB is used as a byte offset 
into the jump table within the 
attribute table pointed to by the 
JTAB register, and the IPC register 
is set to the byte address 
(JTAB[SB]) - contents of 
(JTAB[SB]) . 

FJP 161 SB False jump. Jump (as described for 

UJP) if tos is FALSE. 

XJP 172 W1 , W2,< case table >,W3 

Case jump. W1 is word-aligned and the 
minimum case selector of the case 
table. W2 is the maximum case 
selector. W3 is an unconditional 
jump offset past the case table. 
The case table is 
( W2 - W1 -f 1 ) words long, 
and contains self-relative pointers. 




I 



I 



If tos , the case selector 
expression, is not in the range 
W1..W2 .then point the IPC 
register at W3 . Otherwise, use 
( tos - W1 ) as an index into the 
case table, and set the IPC 
register to the byte address 
(casetable[ tos - W1 ]) minus 
the contents of 
(casetable[ tos - W1 ]), and 
continue execution. 



Procedure and Function Calls 



The general method of procedure/function invocation is: 

1 . Find the procedure code of the called procedure. 

2 . From the DATA SIZE and PARAMETER SIZE fields of the attribute table 
of the called procedure, determine the size (in bytes) of the needed 
activation record, and extend the program stack by that number of 
bytes. 

3. Copy the number of bytes specified by the PARAMETER SIZE field from 
the top of the evaluation stack (tos) to the beginning of the space just 
allocated on the program stack. This passes parameters to the new 
procedure from its calling procedure. 

4. Build a markstack, saving the SP, IPC, XIPC, SEG, JTAB, KP, STRP, MP, 
and a static link pointer (MSSTAT) to the most recent activation record of 
the procedure that is the lexical parent of the called procedure. 

5. Calculate new values for the SP, IPC, XIPC, JTAB, XJTAB, MP, XMP, and 
if necessary, the SEG, and XSEG registers. Issue an execution error if 
the program stack overflows. 

6. If the called procedure has a lexical level of - 1 or (in other words, it is 
a base procedure) save the value of the BASE register on the evaluation 
stack and then equate the BASE register with the MP register, 

7. Save the value of the KP register on the program stack. 
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8. Save the value of the STRP register on the program stack. 

9 . Calculate a new value for the KP register to set it one word beyond the 
value of the STRP register. 

CLP 206 UB Calllocal procedure. Call procedure 

number UB .which is an 
immediate child of the currently 
executing procedure and in the 
same segment. The MSSTAT field 
(static link) of the markstack is set 
to the value of the old MP register. 

CGP 207 UB Call global procedure. Call procedure 

number UB , which is at lexical 
level 1 and in the same segment 
as the currently executing 
procedure. The MSSTAT field 
(static link) of the markstack is set 
to the value of the BASE register. 

CIP 174 UB Call intermediate procedure. Call 

procedure number UB in the 
same segment as the currently 
executing procedure. The 
MSSTAT field (static link) of the 
markstack is set by looking up the 
dynamic chain (MSDYN fields) 
until an activation record is found 
whose caller had a lexical level one 
less than the procedure being 
called. Use that activation record's 
MSSTAT field (static link) as the 
static link of the new markstack. 

CBP 194 UB Call base procedure. Call procedure 

number UB , which is at lexical 
level -1 or 0. The MSSTAT field 
(static link) of the markstack is set 
to the MSSTAT field in the 
activation record of the procedure 
pointed to by the BASE register. 
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The value of the BASE register is 
saved on the evaluation stack, 
after which it is set to point to the 
MSSTAT field of the activation 
record just created. 

CXP 205 UB1,UB2 Call EXTERNAL procedure. Call 

procedure number UB2 , in 
segment UB1 . Used to call any 
procedure not in the same 
segment as the calling procedure, 
including base procedures. If the 
desired segment is not already in 
memory, it is read from disk. Build 
an activation record. Calculate the 
static link for the markstack (if the 
called procedure has a lex level of 
-1 orO, set as in the CBP 
instruction; otherwise set as in the 
CIP instruction). 

CSP 158 UB Call standard procedure. Used to call 

standard procedures built into the 
P-machine. 

RNP 1 73 DB Return from non-base procedure. DB is 

the number of words that should 
be returned as a function value 
(0 for procedures, 1 for non-real 
functions, and 2 for real 
functions). Copy DB words from 
the higher addresses of the 
current procedure's activation 
record, and push them onto the 
evaluation stack. Then copy the 
information in the current 
procedure's markstack fields into 
the psuedo-registers to restore 
the calling procedure's correct 
environment. 
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RBP 1 93 DB Return from base procedure. Move the 

value of the BASE register saved 
on the evaluation stack by a CBP 
back into the BASE register, and 
then proceed as in the RNP 
instruction. 

EXIT 158 4 Exit from procedure, tos is the 

procedure number, tos-1 is the 
segment number. First, set the 
MSIPC field to point to the exit 
code of the currently executing 
procedure. 

If the current procedure is not the 
one to exit from , change the 
MSIPC field of each markstack to 
point to the exit code of the 
procedure that invoked it, until the 
desired procedure is found. Then 
continue execution. 

If at any time the saved MSIPC 
field of the main body of the 
operating system is about to be 
changed, give an execution error. 

System Support Procedures 



See the Apple III Pascal Programmer's Manual, Volume 1 for a description of 
the Pascal language level interface to these functions. 

Byte Array Procedures 

FLC 158 10 Fillchar. tos is the source character. 

tos— 1 is the number of bytes in 
the source character which are to 
be filled, tos - 2 is a byte pointer 
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SCN 158 11 



MVL 158 02 



to the first byte to be filled in the 
destination. Copy the character 
tos into tos-1 characters of the 
destination. 

Scan, tos is a two-byte quantity (usually 
the default integer 0) which is 
pushed, but later discarded 
without being used in this 
implementation .tos-1 is a byte 
pointer to the first character to be 
scanned, tos - 2 is the character 
against which each scanned 
character of the array is to be 
checked, tos -3 is if the check 
is for equality, or 1 if the check is 
for inequality, tos - 4 specifies the 
maximum number of characters to 
be scanned (scan to the left if 
negative). If a character check 
yields TRUE, push the number of 
characters scanned (negative, if 
scanning to the left). If tos -4 
characters are scanned before 
character check yields TRUE, 
push tos -4 . 

Moveleft. tos specifies the number of 
bytes to move .tos-1 is a byte 
pointer to the first destination byte, 
tos - 2 is a byte pointer to the first 
source byte. Copy tos bytes 
from the source to the destination, 
proceeding from left to right 
through both source and 
destination. 
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MVR 158 03 Moveright. tos specif ies the number of 

bytesto move. tos— 1 is a byte 
pointer to the first destination byte, 
tos -2 is a byte pointer to the first 
source byte. Copy tos bytes 
from the source to the destination, 
proceeding from right to left 
through both source and 
destination. 



Compiler Procedures 

BPT 213 B Breakpoint. Not used (acts as a NOP). 

TRS 158 08 Treesearch. tos-2 is a byte pointer to 

the root of a binary tree, tos is a 
byte pointer to a location which 
contains the address of an eight- 
character name to be found or 
placed in the tree. Search the tree, 
looking for a record with the 
required name. On completion of 
the search , store the address of 
the last node visited, into the 
location pointed to by the byte 
pointer tos— 1 , and push the 
result of the search: 

if the last node was a record 
with the search name, 

1 if the search name should be 
a new record , attached to 
the last tree node by the 
Right Link, 

— 1 if the search name should be 
a new record, attached to 
the last tree node by the Left 
Link. 
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This is an assembly-language 
binary tree search used by the 
Compiler. It is fast, but does not 60 
type checking on the parameters. 
The binary tree uses nodes of type 

CTP - RECORD 

NAME: PACKED ARRAY CI . .83 

OF CHAR; 
LLINK, RLINK: ACTP; 



END; 



IDS 



158 07 



Idsearch. Used by the Compiler to parse 
reserved words and identifiers. 



Miscellaneous 



TIM 



XIT 



1 58 09 Time. Pop two pointers to two integers, 

and place zero in both integers. 

2 1 4 Exit the operating system. Do a warm 

boot of the system, as the 
operating system's H(alt 
command. 



NOP 



215 



No operation. Sometimes used to 

reserve space in the code for later 
additions. 
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Programming Techniques 



This chapter Is a collection of useful techniques and hints to use while 
programming with the Apple III Pascal system. It is divided into two parts: the 
first deals with the Pascal language, and the second discusses assembly- 
language techniques. 

Apple III Packing Algorithm 



Simple types (INTEGER, BOOLEAN, and so forth) in UCSD Pascal have two 
standard sizes, depending on whether or not they are packed. These 
standard sizes are: 



Type 


Standard Unpacked Size 


Standard Packed Size 


Integer 


one word (16 bits) 


one word 


Real 


two words 


two words 


Char 


one word 


one byte (8 bits) 


Boolean 


one word 


one bit 


Subrange 


one word 


if smallest value > = 0, then 






number of bits in largest 






value else one word 


Scalar 


one word 


number of bits needed to 






represent the number of 






scalars in the scalar list 


Long Integer 


For form INTEGER[I]: 






(1+3) DIV4 + 1 words 


(1+3) DIV 4 + 1 words 


Pointer 


one word 


one word 


String 


For string of max length N: 






(N+2) DIV2words 


(N+2) DIV 2 words 



Programming Techniques 97 



Complex types, including RECORDS, ARRAYS, FILES, and SETS, always 
occupy a whole number of words whether they are packed or not. The 
number of words occupied depends on the internal structure given to the 
type. 



Records 

Each field that is a simple type is allocated a size as indicated above. If the 
record is a packed record, then the packed sizes are allocated. Tag fields, // 
they are associated with a named variable, occupy the same space as they 
would if they were ordinary fields. (Untagged variants occupy no space.) For 
example, the record below indicates the number of words allocated to each 
field. 

PACKED RECORD 

NAME : STRINGt20]; 
SEX : (MALE, FEMALE); 
ID : C..8191; 
MARRIED:BOOLEAN; 
CASE HASCHILDRENlBOOLEAN OF 
TRUE: (NUMCH I LDREN: INTEGER ; 

OLDEST:INTEGER); 
FALSE: (STER I LE : BOOLEAN; 
CASE BOOLEAN OF 
TRUE: (BLOODTYPE:0 

END; 

In this case, the total record size is 1 4 words with the first 1 1 words going to 
the NAME field, the next word for the SEX, ID, MARRIED and HASCHILDREN 
fields, and the last two words either going to the NUMCHILDREN and OLDEST 
fields or to the STERILE and BLOODTYPE fields, depending on the value of 
the HASCHILDREN tagfield. 

Since the allocation of fields is right to left within a word, the SEX, ID, 
MARRIED and HASCHILDREN fields are allocated within word 12 as follows: 

SEX : bit 
ID : bits 1.. 13 
MARRIED : bit 1 4 
HASCHILDREN : bit 1 5 



11 words} 
1 bi t } 



(13 bits 


} 


i1 bit) 




(1 bit) 




l1 word } 




1 word}, 


these overlay 


1 bit } ^ 


the same 


bits) 




3 bits}j 
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NUMCHILDREN and OLDEST are allocated words 13 and 14, respectively. 
However, if this case variant of the record had been declared as 



CASE HASCHILDREN:BOOLEAN OF 

TRUE: (NUMCHILDREN, OLDEST : INTEGER) ; 



then OLDEST would have been allocated word 1 3 and NUMCHILDREN 
word 1 4, since the compiler allocates fields backwards within a such a list. 
(This backwards allocation aiso applies to lists of variables in VAR 
declarations.) 

If a field is packable, but there is not enough room in a given word for that field 
to fit, the entire field is moved to the beginning of the next word. This leaves 
some unused space in the first word. An example is 

TYPE PART = PACKED RECORD 



In this example bits 9 through 1 5 of the first word go unused because the 
integer won't fit there. Also, note that bits 7 through 1 5 of the third word go 
unused, but since the record size must be a whole number of words, the total 
record size is exactly three words. 

Accordingly, if PART is used as part of a larger record 



PARTNUM:0. .511 ; 
AMOUNT: INTEGER; 
ORDERQTY: 1 . .99; 



{word 1 , bits 0. .8} 
{word 2 , all bits) 
{word 3 , bits . .6 } 



END; 



PARTSHEET 



PACKED RECORD 



WHICHPART:PART; 
INITIAL: CHAR; 



{ words 1 . .3 } 

{ word 4, bits 0. .7) 



END; 



the record type PART is considered to be a three-word chunk, and although 
the INITIAL field would have fit into the third word of PART, it is not put there. 
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Arrays 

For an array to be packed, the size of the array element must be eight bits or 
less. Arrays of records or other complex types are not packed. If the element 
size is eight bits or less, then each 1 6-bit word of the array gets the largest 
possible integral number of elements. In the array 

PACKED ARRAY t-10..10] OF 9 . .7 ; 

each word of the array contains five three-bit elements (with bit 1 5 of each 
word empty); the array contains a total of five words (2 1 divided by 5, 
rounded up). Array elements are allocated in increasing word order in memory 
and in increasing bit order within each word. 

Note that the array declarations 

PACKED ARRAY t1..10] OF PACKED ARRAY [1..2] OF BOOLEAN; 

PACKED ARRAY 1..2] OF BOOLEAN; 

ARRAY OF PACKED ARRAY [1..2] OF BOOLEAN; 

are all equivalent, and that the "inner" array of booleans gets packed into one 
word (1 4 bits unused), while the "outer" array of arrays does not get packed 
(the size of its element is one word). 

Sets 

Packed or unpacked, a set occupies the number of bits equal to the largest 
element's ordinal value plus one and is rounded up to a whole number of 
words. For example, 

TYPE 

A = SET OF 2«. .63; 
6 - SET OF 40. .64; 

allocates four words for A and five words for B. 
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Files 

All files, packed or unpacked, currently occupy at least 550 words that are 
distributed as follows: 

256 words for the block buffer 
256 words for the index block buffer 
38 words for the File Information Block 

Typed files occupy an additional amount of space equal to the size of the type 
for the file window. Files of type TEXT or INTERACTIVE occupy 551 words. 

Pascal Language Techniques 



This section includes discussions of efficient use of variable references, 
CASE statements, string and packed array constants, and SEGMENT 
procedures. A group of useful Compiler options are also discussed. 

Dynamic Text Arrays 

The following fragment of Pascal-code demonstrates a method by which you 
can dynamically allocate a variable-length packed array of characters (a text 
array). The procedure works in the following manner: 

1 . A check is made to ensure that there is enough space for the array. If 
there is not, a message is displayed, and the procedure is exited. 

2. The number of bytes available for a dynamic buffer is calculated. 

3. The first block of the buffer is allocated, and a pointer to its head is 
defined. 

4. Other blocks are sequentially allocated until there is not enough space 
left to allocate another. 

5. All of the blocks in the buffer are transformed into a packed array of 
characters. 
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PROCEDURE CreateArray; 



CONST 

FreeSpaco= 2000; 

RytesInHlock= 511; 
WordsInBlock= 256; 
BytesInArray= 8000; 
IlaxArray Index* 7999; 



{Words of stack/heap space to be 

reserved to prevent overflow} 
{Number of bytes in a block minus one} 
{Number of words in a block} 
{Maximum number of bytes in text array) 
{^laximum index into text array} 



{Note: the values assigned to BytesInArray and llaxArraylndex can approach 
32767, but are limited by program and memory size} 

TYPE 

HlockBuffer= PAQ^ED ARRAY [ 0. .BytesInBlock] OF CHAR; 

{The block-sized input/output buffer} 
TextArray- PACKED ARRAY [ . .IiaxAr ray Index ] OF CHAR; 

{The text array, divided into BlockBuffer- 
sized chunks} 



VAR 



Loop , 

Words InAr ray , 
HytesCalcBuf fer, 
WordsCalcBuf fer, 
BytesActualBuf f er 
INTEGER; 

PtrBuf fer 
PtrArray : 
TrixBuf fer 



"BlockBuf fer; 
TextArray ; 
PAQCED RECORD 



CASE BOOLEAN 
TRUE: (IB: 
FALSE: (BB; 

END: 



{riaximum number of words in the array} 
{Number of bytes allowed in the buffer} 
{Number of words allowed in the buffer} 
{Number of bytes currently in the buffer} 

{Pointer to buffer} 
{Pointer to text array} 
{Record for conversion of buffer to a 
text array, and for use as a temporary 
buffer pointer} 

OF 

"TextArray); 
'^BlockBuffer); 



BEGIN 



{Check to see if there is enough room to allocate the buffer 
for the array. Note: ME^IAVAIL returns the number of available 
words • } 

IF MEIIAVAIL < Freespace THEN BEGIN 

WRITELN ('Not enough room for text buffer.'); 
READLN; 

EXIT (CreateArray) 
END; 
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{Calculate the number of bytes allowed in the buffer; defined as 
the smaller of "available memory" or the defined array size 
(BytesInArray)} 
WordsCalcBuf fer := MEliAVAIL - Freespace; 
WordsInArray (BytesInArray DIV 2); 

IF WordsCalcBuf fer > WordsInArray THEN 

HytesCalcBuf f er :« BytesInArray 
KLSK BytesCalcBuf fer:= WordsCalcBuf fer * 2; 

{Allocate the space for the buffer} 

NEW (TrixBuffer.BB); {Allocate the first block, with a 



{Allocate the remaining blocks in the buffer. Since the 2nd 
through nth blocks are allocated sequentially after the 1st 
block, their pointers are discarded.} 

FOR Loop:«= 1 to (BytesCalcBuf fer DIV WordsInBlock - 1) DO 
NEW (FtrBuffer); 

{Transform the buffer into an array to enable byte-oriented procedures 
and functions} 

PtrArray:« TrixBuf f er. IB; 
BytesActualBuf fer:« BytesCalcBuf fer; 



Once the text array has been created, you are free to use byte-oriented 
procedures and functions, such as SCAN and MOVELEFT, with Ptr Array as a 
parameter. Individual characters within the array can be referenced as 

PtrArrayA[Element] 

where Element is in the range 0. .BytesCalcBuf fer. If you attempt to write to 
elements outside of this range, you will probably overwrite part of your 
program. 



pointer to its head} 



Segment Procedures 



There is a limit of 1 60 procedures per segment (no more than 1 49 of which 
can be P-code procedures). If you require a greater number of procedures 
within a segment, use nested SEGMENT procedures. 



Programming Techniques 1 03 



Variable Declarations 

Declare the most-frequently referenced variables in the first 1 6 words of each 
procedure's data space. Referencing the first 1 6 words in the activation 
record of a procedure is faster and requires less code than does referencing 
other variables in the activation record, because special P-codes exist for 
references to the first 1 6 words. 



String and Packed Array Constants 

string and packed array constants are stored in a linked list on the program 
stack. Each time a given string or packed array constant is referenced, the 
linked list must be traversed until the desired constant is located. A lengthy 
linked list will decrease program performance; instead, setting variables to 
constant values will improve performance. 



Case Statements 

Avoid using CASE statements with widely spaced case selectors. To 
implement a CASE statement, the Compiler builds a table in the code with an 
entry for each possible case selector from the smallest actually used to the 
largest. For example, 

CASE letter OF ' a ' , ' g ' , ' m' , ' z • 

will cause a table with 26 jump vectors to be built. Consider substituting 
nested IF..THEN..ELSE's in place of such CASE statements. 



Private Files 

The Compiler E+ option allows declaration of file variables in the 
IMPLEMENTATION part (and not just the INTERFACE part) of units. Files 
declared in the INTERFACE of a unit or in a VAR declaration of the 
IMPLEMENTATION of a unit are global, and a 1 K byte I/O buffer is allocated as 
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long as the program Is running. Files declared in procedure headings of the 
IMPLEMENTATION of a unit are private to the unit, and their 1 K byte I/O buffer 
is allocated only as long as the procedure is active. Declaring files in the 
procedure heading of the IMPLEMENTATION of units allows you to regain the 
1 K bytes of the I/O buffer when the procedure terminates. 

Private files will only work with SOS-formatted disks, and not with Apple II 
UCSD format disks. 

The lOCHECK and RANGECHECK Compiler Options 

These compiler options provide runtime error checking. You can use I - and 
R- to defeat the checking, which will increase execution speed and decrease 
code size, at the expense of decreased automatic error checking. 

The Resident Compiler Option 

When there are no more active invocations of procedures in a segment, the 
segment code is removed from memory. Loading segments requires time and 
slows program execution. You can increase execution speed at the expense 
of additional memory by use of the RESIDENT Compiler option, which allows 
you to specify certain units and/or SEGMENT procedures to remain resident. 
In a computer with a large amount of memory (for example, 256K bytes) you 
can increase execution speed by keeping a large number of segments 
resident. 

Residence Chains 

The following fragment of Pascal code demonstrates a method for controlling 
the residence (and hence swapping) of segments in a Pascal program 
depending on the size of the system. The procedure INITCODE, not 
presented here, would presumably determine the size of available memory on 
the system on which the program is running. On systems beneath a certain 
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size, all segments except PERMAMENT would be swapped in and out under 
system control as indicated by the NOLOAD compiler option. For mid-sized 
configurations, the additional segments A, S, and C would also be 
permanently resident. On the largest configurations, D, E, and Fwould also be 
resident. 

PROGRAM ExanpleProgram; 

USES {$Using SOSIO.CODE} SOSIO, {Uses SOS_IO memory management procedures 

in functional form to discover the memory available in the system} 
Permanent, A, B, C, D, E, F, G, H; 



TYPE 



bbpp 



PACKED RECORD 
pp, bb: 0..255; 

END; 



{bank/page (bb:pp) from SOS find_seg} 



{Used to find memory available} 



VAR 



SwapAll, SwapSome 



BOOLEAN; 



f ind^plist : 



paq:ed record 



{SOS find s eg pa ram list} 



pages: integer; 
base: bbpp; 
limit: bbpp; 
segnum: integer; 
rc: integer; 



END; 



PROCDURE nain; 
BEGIN 



END; 



PROCEDURE InitCode; 

VAR rc: Integer; {Return code from S()S_REL_SEG} 

BEGIN 

{Uses FIND_SEG in SOS_IO to determine memory available; sets SwapAll and 

Swap Some} 
SwapAll := FALSE; 
SwapSome ;« FALSE; 

WITH f ind_plist DO 
BEGIN 

pages maxint; {try to get all we can} 

IF NOT sos_f ind_seg(2, {may cross bank boundaries} 

127, { $7F, a user segment type} 

findjlist) THEN 

BEGIN 

{SOS_FIND_SEG returns FALSE if tbe number of pages originally 
requested cannot be allocated; the maximum number of pages available 
is placed in the pages field of FIND_PLIST in that case. We call 
SOS_FIND_SEG again to be sure we can get it.} 

IF NOT sos_f ind_seg(2, 127, findjlist) THEN 
BEGIN 

pages :='0; 
END; 
END; 

{The pages field now contains the largest number of 256 byte pages 
available on the system.} 
IF pages > 10 {You must pick your own number! } THEN 

SwapAll :« TRUE 
ELSE IF pages > THEN 

SwapSome :^ TRUE; 
{Now release the segment} 

IF NOT sos_rel_seg(f ind_plist.segnum, rc) THEN 

writelnC Could not release segment (SOS release^^seg error ', rc, ')'); 
END; 

• • • . 

END; 

PROCEDURE Get Rest; 
BEGIN 

{$RESIDENT D, RESIDENT E,RESIDENT F} {Note that G and H are swapped on 

all systems.} 

Main; 
END; 



PROCEDURE Get Some; 
BEGIN 

{$R A,R B,R C} {Note that R is an abbreviation for RESIDENT compiler 
option. } 

IF Swap Some THEN 

BEGIN 

Main; 

END 
ELSE 

BEGIN 

GetRest; 

END; 

END; 
BEGIN 

{$R Permanent ,NOLOAD+} {Permanent is present on all systems; don't let 

anything else be loaded unless some part active} 

InitCode; {Checks available memory; sets SwapAll and Swap Some.} 

IF SwapAll THEN 

BEGIN 

Main; 

END 
ELSE 

BEGIN 

Get Some; 

END; 

END. 



Pascal Unit Numbers and SOS Device Names and 
Numbers 

The following Pascal program makes use of the functional version of SOS 
device calls available through the unit SOS^IO. It translates between SOS 
device names, SOS device numbers, and Pascal unit numbers. 
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{ Start of Pascal Denonstration Prof;raTn: TestDevTranslation } 

PROGRAM TestDevTranslation; 

USES {$Using SOSIO.CODE} SOSIO; {Uses SOS_IO device calls in functional form} 

VAR InString, {user input} 

SosName: STRING; {Sos Name of device specified} 

PasNum, {Pascal Unit # of device specified} 

SosNum, {Sos device number of device specified} 

RetCode: INTEGER; {Return code from SOS calls} 

Error: BOOLEAN; {no device specified} 

DevList: PACKED ARRAY [0..101 OF 0..255; 

{Device information list returned by SOS} 

FUNCTION GetSOSNum(PasNum:INTEGER):INTEGER;FORWARD; 
FUNCTION GetPascalNumCSOSNum: INTEGER) :INTEGER;FORWARD; 



PROCEDURE Introduction; 
BEGIN 

WRITELN( 'Welcome to the wonderful world of device translation!'); 
WRITELN(*Type in a device and I will translate it*'); 

WRITELN( 'Formats are: SOS device number (e.g. 1) or Pascal unit (e.g. #4)'); 

WRITELNCor even a SOS device name (e.g. .rs232)'); 

WRITELN; 

WRITELNCType just a [RETURN] to exit'); 

WRITELN; 

END; 

FUNCTION GetSOSNum{ PasNum: INTEGER) : INTEGER} ; 

{returns SOS device number of unit numbered PasNum; 
if no such unit or no SOS device in that unit #} 
TYPE Byte = 0..255; 
VAR 

Data: PACKED RECORD 

RegularUnits: PACKED ARRAY [1..20] OF Byte; 
UserUnits: PACKED ARRAY [128. .147] OF Byte; 
END; 
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♦ 

BEGIN 

UnitStatus(0,Data,0) ; {ask interpreter for table} 

IF PasNum IN [1..201 THEN 
BEGIN 

GetSOSNum :« Data. RegularUnits [PasNum] ; 
END 

ELSE IF PasNum in [128. .147] THEN 
BEGIN 

GetSOSNum : Data.UserUnits[PasNum] ; 
END 
ELSE 

BEGIN 

GetSOSNum :« 0; 
END; 

END; 



FUNCTION GetPascalNum{SOSNum: INTEGER) : INTEGER} ; 

{returns the Pascal unit number of the SOS device numbered SOSNum; 
if none found } 

TYPE Byte « 0..255; 
VAR 

PasNum: INTEGER; 
Data: PACKED RECORD 

RegularUnits: PACKED ARRAY [1..20] OF Byte; 

UserUnits: PACKED ARRAY [128.. 147] OF Byte; 
END; 



BEGIN 

IF SosNum « THEN 
BEGIN 

PasNum :« 0; {avoid "holes*V in Unittable} 
END 
ELSE 

BEGIN 

UnitStatus(0,Data,0) ; {ask interpreter for table} 

PasNum :« SCAN( 4 1 , «CHR(SOSNum) ,Data)+l ; {find SOSNum in table} 

IF PasNum =42 THEN 
BEGIN 

{scanned off end of table} 

PasNum := 0; 

END 

ELSE IF PasNum > 20 THEN 
BEGIN 

{adjust index appropriately} 
PasNum :« PasNum+107 ; 
END; 
END; 

GetPascalNum := PasNum; 
END; 
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if 

FUNCTION Number(S: STRING; VAR n: INTEGER) : BOOLEAN; 

VAR i: INTEGER; 
BEGIN 

NUMBER :» FALSE; 

S :« CONCAT(S,* »); 

n :« 0; 

i 1; 

WHILE S[i] IN ['0^,'9»] DO 
BEGIN 

Number :« TRUE; 

n :» n*10+ORD(S[il)-ORD('0'); 

i :« i+1; 

END; 

END; 

BEGIN 

Introduction; 
REPEAT 

READLN(InString); 
IF LENGTH(InString) >0 THEN 
BEGIN 

Error :» FALSE; 
IF InString[l] « ' THEN 
BEGIN 

{must be a SOS device name} 
SosName Inst ring; 

IF NOT SOS_GetJ)_Num(InString, SosNum, RetCode) THEN 
BEGIN 

WritelnCSOS error RetCode, * f rom SOS_Get_D_Num' ) ; 
END; 

PasNum := GetPascalNum( SosNum) ; 
IF PasNum « THEN SosName :««*•; 
END 

ELSE IF InString[l] « '#» THEN 
BEGIN 

{must be a Pascal unit number} 
DeleteClnString, 1, 1) ; {remove # sign} 
IF NumberdnString, PasNum) THEN 
BEGIN 

SosNum :« GetSOSNum(PasNum) ; 

IF NOT SOS_D_Info( SosNum, SosName, DevList, RetCode) THEN 
BEGIN 

Writeln('SOS error RetCode, » from SOS_D_Inf o' ) ; 
END; 

END 



ELSE 

BEGIN 

Error :« TRUE; 
END; 

IF SOSNum « THEN PasNum :« 0; 
END 

ELSE IF Number(InString,SosNum) THEN 
BEGIN 

{must have typed a number} 

IF NOT SOS_D_Inf o(SosNum, SosName, DevList, RetCode) THEN 
BEGIN 

WritelnCSOS error RetCode, • from SOS_D_Inf o' ) ; 
END; 

PasNum :« GetPascalNum(SosNum) ; 
IF PasNum = THEN SosNum 0; 
END 
ELSE 

BEGIN 

Error :* TRUE; 
END; 

{NOT Error »> (SOSNum-0 <-> PasNum^O <«> SosName***) } 
IF SosNum « THEN Error := TRUE; 
IF Error THEN WRITE(CHR( 7) ) {Sound a bell} 
ELSE Writeln(SosName:16, ' <»> ♦,S0SNum:2/ <«> //*, PasNum); 
END; 

UNTIL InString= » ' ; 
END. 

{ End of TestDevTranslation } 

Pascal Use of SOS Extended Memory 

This section describes techniques that can be used to access extra memory 
available on the larger memory configurations of the Apple III. Before reading 
further, you should review the section System Memory Use in Chapter 3. 

Apple III Pascal is upwardly compatible with Apple II Pascal. One of the 
constraints this imposes on the design of the Apple III system is the restriction 
to a data space of 64K bytes. Although the system uses memory outside this 
data space for SOS, drivers, graphics space, interpreter and code segments, 
this restriction still interferes with programs that handle large quantities of data. 

However, by making use of SOS the Pascal programmer can gain direct 
access to the extra memory. The following assembly-language procedures 



illustrate the techniques involved in accessing more data. These procedures 
ask SOS to allocate more space to the program, to allow the transfer of data to 
and from this space, and then eventually to deallocate the space. More 
elaborate storage allocation schemes may be built on top of this package. In 
the following simple example, after initialization a string is stored in the extra 
space, retrieved, and displayed. 

The routines are presented in two parts. The first is assembly language that 
contains some useful macros, the procedure X^MOVELEFT (an expanded 
version of the Pascal MOVELEFT procedure to move bytes no matter which 
bank is the source or destination), and the function ADDRESS that returns the 
address of its variable. The second part is a Pascal program that demonstrates 
the required declarations and the use of the procedures. 

. Extra Storage Space Assembly-Language Procedures 

.TITLE "Xjnoveleft - Extended moveleft for moving bytes across banks" 

.NOPATCHLIST 

.NOMACROLIST 



«< X_moveleft »> 
Extended version of Pascal's moveleft for moving data across banks 
. , ^^^„„^«^-.-«„« — .* ■ 

This module is the code for the procedure x^moveleft. Xjnoveleft is a 
generalized version of Pascal's moveleft procedure. Functionally, it does 
the same thing, i.e., moves bytes, in ascending order, from a source to a 
destination. But unlike moveleft, x^moveleft can move the bytes no matter 
which bank they are in. It is designed to be used in Pascal programs which 
wish to use the rest of the bank space in larger machines. 

Xjnoveleft has the following Pascal declaration and call: 

PROCEDURE x_movelef t(src_bank, src_addr, 

dst_bank, dst_addr, 
pages, partial: integer); 
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; where: src_bank * bank number (0, 1, 2, ..•) of the source. A special value 

; of means use Pascal's bank. 

; src_addr * address of 256 byte page in the source bank 

; ($0000 to $7FFF). This may be obtained using the 

; function ADDRESS also supplied in this module and 

; described below. 

; dst__bank = bank number of destination. A special value of -1 means 
; use Pascal's bank. 

; dst_addr « page address in the destination bank ($0000 to $7FFF). As 

; with src_addr, the ADDRESS function may be used to get the 

; address of a Pascal variable. 

; pages = number of whole 256-byte pages to move. 

; partial * number of bytes in final (or only page) to move. 

; X-movelef t will move pages*256+partial bytes from the source at the address 

; src_bank: src^addr ($bb:xxxx) to the destination at address dst__bank: dst^addr. 

; A -1 for a bank value means to use Pascal's bank. Thus the following two calls 

; are functionally equivalent: 

; x^movelef t(-l; address(s) , -1, address(d) , 0, n) moveleft(s, d, n) 

; Segment and bank values for data may be obtained by the SOS request^seg or 
; find^seg calls. They return segment addresses of the form $bb:pp, where the 
; pp is in the range $20 to $9F for banked-switched or segment addressing. 
; Xjmovebytes uses extended indirect addressing. Thus the pp value must be 
; converted to a A-byte address and offset by $2000 to produce addresses in the 
; range $0000 to $FFFF. This could produce an address of the form $bb:00xx, 
; i.e., a reference to a zero page. Xjnovebytes checks for this case and 
; adjusts the bank and address values accordingly ($bb:00xx becomes $bb-l:80xx). 
.PAGE 

; Also supplied in this module is the function ADDRESS: 
; FUNCTION address (VAR x): integer; 

; This returns the address of x as the value of the function. It is useful for 
; moving Pascal data with XJIOVELEFT as illustrated above. 



Macro to push a word on to the stack. 

.MACRO PUSH 
LDA %1+1 
PHA 

LDA ' %1 

PHA 

.ENDM 
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Macro to pop the stack into a word 

.MACRO POP 
PLA 

STA %1 
PLA 

STA %1+1 

.ENDM 

.PAGE 

The following macro saves SRC_BANK and DST^BANK (passed as the 

first parameter, %1, an extended address bank pointer) in SAVE_SRC_BANK 

and SAVE_pST_BANK, respectively, and then sets the new value from 

the stack (popping it off). It turns the high bit on to enable indirect 

addressing. 

Follows convention that value of -1 means that the Pascal bank is to 
be used. It also checks the address currently pointed to by the corresponding 
word in zero page, and modifies it and %1 (bank register), if necessary, to 
make sure that the address does not point to the zero page of the bank pair 
(to avoid the hole in the memory map). Zero page wraparound during execution 
is taken care of by the main loop. 

This macro is commented as a pseudo procedure with the following declaration: 

PROCEDURE setbank(newbank: integer; VAR bank, temp: byte; addr: integer; ); 

where: bank « extended address bank pointer (%1, "src^bank" or "dst^bank") 

newbank = new value for bank which is popped off the stack 

(from x^moveleft's call parameter list) by this macro. 

temp = place to save bank's former value before it is clobbered. 

Uses textual macro substitution to generate correct name. 

addr « a page address (src^addr or dst^addr) which is always 

$1601 below the bank register. We look at the msb here, 
hence, we look at bank-$1601+l. 
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.MACRO 


SETBANK 


; PROCEDURE setbank( newbank: integer; 
; VAR bank, temp: byte; 
; VAR addr: integer); 


LDA 


%1 


; BEGIN {setbank} 


STA 


SAVE%1 


temp J* bank; {save Pascal's value} 


PLA 






CMP 


#OFF ; 


IF newbankO-1 THEN 


BEQ 


$1 


bank :« newbank+$80; {high bit on} 


ORA 


#80 ; 




STA 


%1 




LDA 


%1-1601+1 , 


IF addr<256 THEN {have banktOOxx} 


BNE 


$3 


BEGIN {make bank-l:80xx} 


LDA 


#80 ; 


addr :« addr+$8000; 


STA 


%1-1601+1 , 




DEC 


%1 ; 


bank : « bank-1 ; 


PLA 




END; 


.ENDM 




END; {setbank} 


.PAGE 







The following macro guarantees that the base pointer %1 (an address) will not 
wrap into zero page during next 256 increments of the pointer. If it would, 
then adjust the address to be in the first bank .of a bank pair and increment 
the bank, i.e., bb:nnnn becomes bb+1 :nnnn-$8000. Note that the corresponding 
bank register is at the address+$1601 . 



$1 



.MACRO 

LDA 

CMP 

BCC 

SBC 

STA 

INC 

.ENDM 

.PROC 



CHKWRAP 

#OFF 

$1 

#80 

%i+l 

%14-1601 

X M0VELEFT,6 



PROCEDURE chkwrapCaddress: integer); 
BEGIN {chkwrap} 

IF address>«$FFOO THEN 

BEGIN {set to next bank} 
address :« address-$8000; 
bank :« bank+1 ; 
END; 
END; {chkwrap} 



PROCEDURE x^movelef t(src_bank, src_addr, 

dst^bank, dst^addr, 
pages, partial: integer); 



; Move pages*256+partial bytes from the address src_bank: src_addr (extended 
; indirect addressing form bb:xxxx) to address dst_^bank:dst_addr . A bank of 
; *1 means to use the Pascal bank. 

SRC_ADDR .EQU OEO ; page ptr to read bytes from 

SRC_BANK .EQU 16014-SRC_ADDR ; X-byte for src_addr 



DST ADDR 



.EQU 



0E2 



; page ptr to write bytes to 
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■r 



DST BANK 



.EQU 



1601+DST ADDR 



X byte for dst addr 



RETURN .EQU 

SAVE_SRC_BANK .EQU 2 
SAVE DST BANK .EQU 3 



return address 

used to hold $16El across routine 
used to hold $16E3 across routine 



COUNT_Z 
COUNTRY 
COUNT X 



.EQU 
.EQU 
.EQU 



»»2»*-byte of number of bytes to move 
"Y"-byte 

"X"-"byte (keep count bytes in order) 



POP 


RETURN 


POP 


COUNT_Z 


PLA 




CLC 




ADC 


COUNT Y 


STA 


COUNTRY 


PLA 




ADC 


#0 


STA 


COUNT_X 


POP 


DST ADDR 


SETBANK 


DST BANK 


POP 


SRC ADDR 


SETBANK 


SRC BANK 



MOVE PAGES 



CHKWRAP DST_ADDR 
CHKWRAP SRCJVDDR 
LDA COUNTRY 
BNE PAGE_LOOP 
LDA COUNT_X 
BEQ PARTIAL 
DEC COUNT X 



PRO CEDURE xjno ve 1 e f t ( s r c_ban k , s r c_a d d r , 

d s t^bank , d s t^^addr , 
pages, partial: integer); 

BEGIN {x_moveleft} 

{set x,y, z values to reflect the 
bytes to move: x*256*256+Y*256+2} 
count_z :» partial MOD 256; 
country :« (pages MOD 256)+ 

(partial DIV 256); 
count X :« pages DIV 256; 



{pop rest of the parameters} 
setbank(dst_addr ,dsf_^bank, save_dst_^bank) ; 

setbank(src_^addr , src^bank, save^^sr embank) ; 

FOR i:«count_x downto 1 DO 

BEGIN {move count_x*256 pages} 
chkwrap(dst_addr) ; 
chkwrap(src__addr) ; 
FOR j:«count_y DOWNTO 1 DO 
BEGIN {move count y pages} 



PAGE LOOP 


LDY 


#0 


; {move 1 page of 256 bytes} 


$1 


LDA 


@SRC_ADDR,Y 


; FOR y:«0 TO 255 DO 




STA 


OD^T a DDT? Y 


• H^f addr'^'rvl !« r rp— a Hd t f v 1 • 

K VIOL. CIVIUI. i, J J * OUVIX. LJ^J) 




INY 








BNE 


$1 


; 




INC 


SRC ADDR+l 


; src addr :» src_addr-l-256; 




INC 


DST ADDR+1 


; dst_addr dst_addr+256; 




DEC 


COUNT Y 


; END; {moving count y pages} 




JMP 


MOVE JP AGES ; 


count y :« 256; {count x*256 pages} 






> 


END; {moving count x*256 pages} 


PARTIAL 


LDA 


COUNT Z ; 


{move remaining partial page} 




BEQ 


EXIT ; 


FOR y:«0 TO count_2 DO 




LDY 


#0 ; 


dst addr^[y] :« src^^addr^ [y ] ; 


$1 


LDA 


@SRC ADDR,Y 


; 




STA 


(?DST_ADDR,Y 


; 




INY 








PPV 

L.r I 


COUNT Z 






BNE 


$1 




EXIT 


LDA 


SAVE SRC BANK 


; {put things back the way they were} 




STA 


SRC BANK 


;src bank :« save_sr embank; 




LDA 


SAVE DST BANK 


;dst bank save dst bank; 




STA 


DST BANK 






PUSH 


RETURN 






RTS 


; END; {xjnovelef t } 




.FUNC 


ADDRESS,! 


5 


; FUNCTION address (VAR 


x): integer; 




; Returns 


the address 


of "x". 




RETURN 


.EQU 









POP 


RETURN 


; FUNCTION address(VAR x) : integer; 








; BEGIN {address} 




PLA 








PLA 




; {Remove the extra words on the} 




PLA 




; {stack because it's a function} 




PLA 








PUSH 


RETURN 


; address :» tos; {parara is still 








; on top of stack} 




RTS 




; END; {address} 



> 



.END 

- End of Extra Storage Space Assembly-Language Procedures 



118 Pascal Technical Reference Manual 



C * — ...^ - ^ 

<<< USES-X-MOVELEFT >>> 
* - — - — — — *] 

PROGRAM uses_x_movelef t; 

USES {$USING SOSIO.CODE} sosio; {This program uses the SOS_IO package in 
functional form to access the SOS memory management calls} 

I* * 

I Constants | 
« «*} 

CONST 

MaxString » 100; {Maximum number of strings which can be entered in 
the sample program} 

.* 

I Types I 
* — .*} 

TYPE 

bbpp ss 

PACKED RECORD {bank/ page (bb:pp) from find_seg} 

pp, bb: 0..255; 
END; 

I*-. . — . * 

I Global Data | 
* — ... — . — -*.} 

VAR 

i, NumStrings: 0* .MaxStr ing; 

StringLoc: array [ 1 . .MaxString ] OF RECORD 

bank, addr: integer; 
END; 

s: string[255]; 
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{ * 

I Data Used for SOS Segment Manipulations | 
*„ ._„„_._„^. ^-.-^™.„.....*| 

find_pli$t: 

PACKED RECORD {find_seg param list} 

pages: integer; 
base: bbpp; 
limit: bbpp; 
segnum: integer; 
rc: integer; 





END; 




base^bank: 


integer; 


{segment starts in this bank} 


base addr: 


integer; 


{segment starts at this address} 


limit bank: 


integer; 


{segment ends in this bank} 


limit_addr : 


integer; 


{segment ends at this address} 


f ree__bank: 


integer; 


{free space in this bank} 


f ree^addr : 


integer; 


{free space at this address} 



{*_—_ . — _ — — 

I External (assembly) Procedures | 

* . „™_„..^ 

PROCEDURE xjnovelef t(src_bank, src_addr, dst_bank, dst_addr> pages, 

partial: integer); 

EXTERNAL ;' 

FUNCTION address(VAR x) : integer; 
EXTERNAL ; 

{*^^.____«.^„_._«„^_„^ * 

I alloc^^segment - allocate a segment | 

FUNCTION alloc_segment: integer; 

BEGIN {alloc_segment} 
WITH find_plist DO 
BEGIN 

pages :« maxint; {try to get all we can} 

IF NOT sos_f ind_seg(2, {may cross bank boundaries} 

127, { $7F, a user segment type} 
find plist) THEN 
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BEGIN 

{SOS_FIND_SEG returns FALSE if the number of pages originally 
requested cannot be allocated; the maximum number of pages 
available is placed in the pages field of FIND_PLIST in that 
case. We call SOSJFIND_SEG again to be sure we can get it.} 
IF NOT sos_find_seg(2, 127, find_plist) THEN 
BEGIN 
writeln( 

•Cannot allocate segment (SOS find___seg error rc, *)'); 
pages := 0; 
END; 
END; 

base^^bank :» base.bb; 
base^addr :» (base.pp-32)*256; 
limit^^bank := limit. bb; 
limit_addr :« (limit .pp-32)*256-l ; 

free^^bank :« base^bank; 
free^addr :« base^addr; 

alloc^segment :« pages; 
END; {WITH} 
END; {alloc segment} 



.{*-^^„- — ^^„„-.«-^-.^„-.^-. — * 

I free^segment - free the allocated segment | 
it ■ ^-.„^,-.-.«.^- .-.^ — , * } 

PROCEDURE free_segment; 
VAR 

rc: integer; 

BEGIN {free_segment} 

IF NOT sos_rel_seg(f ind_plist.segnum, rc) THEN 

writeln( 'Could not release segment (SOS release_seg error rc, ')'); 

END; {f ree_segment} 
{* ^ — . * 

I alloc - allocate space in the segment | 
* ^ — -.„^- — — — 

PROCEDURE alloc(amount: integer {nbr of bytes to allocate} ; 

VAR bank, addr: integer {location of allocated space} ); 

VAR 

remain: integer; 

top of current_bank: integer; 
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BEGIN {alloc - set bank to -1 if can't get the space} 
bank :« free^^bank; 
addr :« free^addr; 
IF f ree_bank«limlt_bank THEN 
BEGIN 

tGp_of_current_bank :« limit_addr; 
END 

ELSE top_of_current_bank :« 32767; 
remain :« top_of_current_bank-f ree_addr4-l ; 
IF amount >remain THEN 
BEGIN 

IF f ree_bank<limit_bank THEN 
BEGIN 

free^^bank :* f ree^^bank+l ; 
free_addr :« amount-remain; 
END 
ELSE 

BEGIN 

bank :« -^l; 
END; 

END 
ELSE 

BEGIN 

free^addr :» free^addr + amount; 
END; 
END; {alloc} 

— ■ , — . — • 

I putstring - insert string into storage | 
.™_^._„^„„„_«».^^„*} 

PROCEDURE putstringC image: string; VAR bank, addr: integer ); 

VAR image^addr: integer; { address (image) } 

string^len: integer; { number of bytes of string plus 1 } 

BEGIN 

image^addr :« address(image) ; 

string^len := length(image)+l ; {include length byte} 

{allocate space in the extra space for the string} 
alloc(string_^len, bank, addr); 

IF bank<0 THEN 

BEGIN {no more segment space} 

writeln('No space available for string'); 

END {no segment space} 
ELSE {Move the string to the extra memory from the Pascal bank} 

xjnovelef t(~l , image_addr, bank, addr, 0, string len) ; 



END; {putstring} 



I 

{* — — ^.^ ^-.„^— — — -* 

I getstring ~ retrieve string from storage | 

, «„-.«.^— .-..^ — , ★} ' ■ 

PROCEDURE getstring( VAR image: string; bank, addr: integer ); 
VAR image_addr : integer; { address(image) } 
BEGIN 

{ Read the string back } 

image^addr :» address(image) ; 

x^movelef t(bank, addr, -1, image^^addr, 0, 256); 

{We read back 256 bytes since length byte is stored away. We thus can 
read back any string.} 



END; {getstring} 



— ^- — — 

I init - initialization | 
* *} 

PROCEDURE init; 
VAR 

pages: integer; 

BEGIN {init} 

writeln(chr(28) ) ; {Clear viewport} 
writeln; 

write( 'USES^X^MOVELEFT' ) ; 
writeln; 



{Get maximum number of 256 byte pages from SOS} 
pages :« alloc_segment ; 

{Terminate if number of pages is less than 25, an arbitrary number 
in this case. } 
IF pages<25 THEN 
BEGIN 

IF pages>0 THEN f ree_segment ; 

writeln( 'Program terminated due to insufficient memory*); 

exit (PROGRAM); 

END; 

writeln( 'Maximum storage space available is pages, ' pages.'); 
writeln; 



END; {init} 



— * 

I Main Program | 



BEGIN {main program} 
init; 

NumStrings :« 0; 
REPEAT 

{Read in a number of strings into the extra space; build 
an array of addresses} 

writelnC 'Enter a string* Blank line terminates. ') ; 
readln(s); 

NumStrings :« NumStrings+1 ; 

putstring (s, StringLoc [NumStrings 1 . bank, StringLoc [NumStrings ]. addr) 

UNTIL (s«'') OR (NumStrings=MaxString) OR (StringLoc[NumStrings ] .bank<0 ); 

NumStrings :« NumStrings - 1; {Last is invalid: blank or no more room} 

writeln(*Now we write them back out:'); 
writeln; 

FOR i :» 1 TO NumStrings DO 
BEGIN 

getstring (s, StringLoc[i ] .bank, StringLoc[i ] .addr) ; 

writeln(s); 

END; 

writeln; 

writelnC'And that*'s all of them!*); 
free segment; 
END {USES X MOVELEFT} . 



Assembly-Language Techniques 



This section includes a liint on memory usage by segments with assembly- 
language procedures, and a list of useful assembly-language macros. 

Assembly-Language Procedures 

Segments with assembly-language procedures cannot be loaded across 
Apple III bank boundaries. To avoid this, the interpreter automatically selects 
the load location for a segment. Therefore, you should avoid placing 
assembly-language procedures in large segments. You could conceivably 
lose over 1 5K bytes of memory if a 1 6K segment with an assembly-language 
procedure were loaded in the stack/heap space such that it had to be pushed 
up above a bank boundary in the middle of this space. Instead, assembly- 
language procedures should be placed in their own segment and be USEd by 
the host program. 

Macro Directives 

This section consists of a group of macro directives that you may find useful in 
your assembly-language programs. Note: In the Form specification of each 
macro, parameters enclosed within () are required, while those enclosed 
within < > are optional. 

The SOS Macro 

This macro calls the specified SOS service using SOSBLK, a fixed area, as the 
SOS parameter buffer. 

Form: SOS (service) 

service: A SOS call number. 

.MACRO SOS 
BRK 

.BYTE %1 
.WORD SOSBLK 
.ENDM 
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The SOSCALL Macro 

This macro calls the specified SOS service using a user-specified parameter 
buffer. 

Form: SOSCALL (service), (pointer) 
service: A SOS call number, 
pointer: A SOS parameter block pointer. 

.MACRO SOSCALL 
BRK 

.BYTE %1 
.WORD %2 
.ENOM 

The POP Macro 

This macro saves the word on the top of the stack in a specified location; its 
action is complementary to the PUSH macro. 

Form: POP (location) 

location: The address in which the word is to be stored. 

.MACRO POP 
PLA 

STA %1 
PLA 

STA %1+1 
.ENDM 

The PUSH Macro 

This macro pushes the word in a specified location onto the top of the stack; 
its action is complementary to the POP macro. 
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Form: PUSH (location) 

location: The address from which the word is to be taken. 

.MACRO PUSH 

LOA 

PHA 

LOA %1 

PHA 

.ENOM 



The RMVBIAS Macro 

This macro removes from the evaluation stack the four zero bytes (the bias) 
passed for a Pascal function. 

Form: RMVBIAS 

.MACRO 

RMVBIAS 

PLA 

PLA 

PLA 

PLA 

.ENDM 

The MOVE Macro 

This macro moves the word value stored at one location to another location. 
Form: MOVE (from), (to) 

from: The address whose value is to be moved. 

to: The address to which the value is to be moved. 

.MACRO MOVE 

LDA %1 

STA %2 
LDA 

STA %2+1 
.ENDM 
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The DEBUGSTR Macro 

This macro generates ASCII strings to aid debugging, if DEBUG = 1 (TRUE). If 
DEBUG = (FALSE), no strings are generated. 

Form: DEBUGSTR (message), <jumpto> 

message: The message to be inserted into the code as a. ASCII 
directive. Note that four asterisks are added before and after the 
message. 

jumpto: The optional location to which execution should jump (to bypass 
the debug message). 

.MACRO DEBUGSTR 

.IF DEBUG 

.IF • '%2" O " " 

JMP %2 

.ENDC 

.ASCII *%V*" 

.ENDC 

.ENDM 

The LOCALREG Macro 

This macro initializes (zeros) the X-bytes zero-page address-pointer registers 
to access the currently switched-in memory bank. One to four zero-page 
addresses may be specified. The A register is destroyed; X and Y remain 
unchanged. 

Form: PASGALRG (reg1),<reg2>,<reg3>,<reg4> 

regl , reg2, regS, reg4: The locations of the zero-page registers to be 
initialized. Only reg1 is required. 
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.HACRO LOCALREG 
XP6START .EQU 1600 
LOA #0 

XP6START414%1 
I f ^ ^ I I I f 

XPGSTART + H-%2 
XP6START+1+%3 
XPGSTART'»'1*%4 



%4 



STA 
.IF 
STA 
STA 
STA 
.ELSE 

.IF • '^/oS ••<>••• » 

STA XPGSTART+1+%2 

STA XPGSTART+1+%3 

.ELSE 

.IF "^/oa* 



STA 

.ENDC 

.ENDC 

.ENDC 

.ENDM 



XP6START-f1+%2 



The PASCALRG Macro 

This macro initializes the X-bytes of zero-page address-pointer registers to 
access a specific memory bank (in other words, enable enhanced indirect 
addressing). One to four zero-page addresses may be specified. The A 
register is destroyed; X and Y remain unchanged. 

Form: PASCALRG (reg1),<reg2>,<reg3>,<reg4> 

reg1 , reg2, reg3, reg4: These are the locations of the zero-page 
registers to be initialized. Only reg1 is required. 

INITXPG contains the value to which the registers should be initialized. 

.MACRO PASCALRG 

.EQU 16EF 

.EQU 1600 

LDA INITXPG 

STA XPGSTART+1+%1 
.IF • •%4* •<>•••• 

STA XPGSTART-^l+o/oa 

STA XPGSTART + 1'»-%3 

STA XPGSTART-fl+^M 



.ELSE 

. If • •%3 • 

STA XP6START+1+%2 

STA XPGSTART-H+%3 

.ELSE 

.IF • 'ro?' • 

STA XPGSTART-H+%2 

.ENDC 

.ENDC 

.ENDC 

.ENOM 

The SAVEREGS Macro 

This macro saves the values of specified registers starting at a specific zero- 
page location. Any combination of A, X, and Y may be saved. 

Form: SAVEREGS (location), <reg1 >,<reg2>,<reg3> 

location: The zero-page location at which the register values are to be 
saved. If this parameter is omitted, the z PAGE location not 
SPECIFIED message will be displayed. 

reg1 , reg2, regS: The registers from which the values are to be saved; 
they are all optional. 

.MACRO SAVEREGS 



.IF 




1 _ 


lilt 




ZPA6E 


LOCATION NOT 


SPECIFIED 




.ENDC 










.IF 




•<> 


III! 


; Check for first register 


.IF 




1 as 


• 'A* • 


; Accumulator? 


STA 


%1 








.ELSE 










.IF 


• •%2* 


* s 


I iXt • 


; X register? 


STX 


%1 








.ELSE 










.IF 




1 


I 1 Y» • 


;Y register? 


STY 


%^ 








.ENDC 










.ENDC 










.ENDC 










.ENDC 










.IF 


• • %3 • 


•<> 


1 1 1 1 


;Check for second register 


.IF 


• • %3 * 




• • A • • 


; Ac cumu I at or? 


STA 











STX 

.ELSE 

.IF 

STY 

.ENDC 

.ENDC 

. ENDC 

.ENDC 

.IF 

.IF 

STA 

.ELSE 

.IF 

STX 

.ELSE 

.IF 

STY 

.ENDC 

.ENDC 

.ENDC 

.ENDC 

.ENDM 



%1+1 

I • o/j^3 • I » • Y • • 



• •o/^4i i«i » Y» • 



;Y register? 



;Check for third register 
; Accumu lator? 



;X register? 



;Y register? 



The RESTREGS Macro 

This macro restores the values of specified registers, by reading values 
starting from a specific zero-page location. Any combination of A, X, and Y 
may be restored. 

Form: RESTREGS (location), <reg1 >,<reg2>,<reg3> 

location: The zero-page location at which the register values are 
stored. If this parameter is omitted, the 2 PAGE location not 
SPECIFIED message will be displayed. 

reg 1 , reg2 , reg3 : The registers into which the values are to be restored 
they are all optional. 

.MACRO RESTREGS 
.IF 1 1%.) . 1 I I 1 

2PAGE LOCATION NOT SPECIFIED 
• ENDC 
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.IF 




•<>• 


1 1 1 


; Check forfirst register 


.IF 






• A • • 


; Accumu lat or? 


LDA 


%1 








.ELSE 










.IF 




1 1 


•x» • 


;X register? 


LDX 


%1 








.ELSE 










.IF 


• *%Z' 


1 SB * 


1 Y 1 * 


;Y register? 


LDY 


%1 








.ENDC 










.EN DC 










.ENDC 










.ENDC 










.IF 


• • %3 • 


'<>' 


1 t 1 


; Check for second register 


.IF 


• • %3 • 


t ^ 1 


• A • • 


; Ac cumu I ator? 


LDA 










.ELSE 










.IF 


• • %3 • 


1 1 


•X' * 


;X register? 


LDX 










.ELSE 










. IF 


• • %3 • 


• S « 


1 yl 1 


; Y register? 


LDY 










.ENDC 










.ENDC 










.ENDC 










.ENDC 










.IF 




•<>' 


III 


;Check for third register 


.IF 




* ss * 


• A' • 


; Accumu lator? 


LDA 


%1+2 








.ELSE 










.IF 


• V%4* 


1 ss * 


•X* • 


;X register? 


LDX 










.ELSE 










.IF 


• •%4» 




1 Y 1 * 


;Y register? 


LDY 


%1+2 








.ENDC 










.ENDC 










.ENDC 










.ENDC 










.ENDM 











The SET Macro 

This macro sets specific bits within a byte. 
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Form: SET (bits), (byte) 

bits: The bits to be set. 

byte: The address of the byte whose bits are to be set. 



.MACRO SET 

LOA #%1 

ORA %2 

STA %2 
. ENDM 



The RESET Macro 

This macro resets specific bits within a byte. 
Form: RESET (bits), (byte) 

bits: The bits to be reset (set to 0). 

byte: The address of the byte whose bits are to be reset. 



.MACRO RESET 

MASK .EQU FF 

LDA #%1aMASK ;a is EXCLUSIVE OR 

AND %2 

STA %2 
.ENDM 



The SWITCH Macro 

This macro performs an n-way branch based on a switch index. The maximum 
value of the switch index is 1 27 with bounds checking provided as an option. 
The A and Y registers, and the C, Z, and N status flags, are destroyed by the 
macro. The X register is not modified by the macro. 

Form: SWITCH <index>,< bounds), (address table),<* > 

index: The variable that is to be used as the switch index. If it is omitted, 
the accumulator is used as the index. 
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bounds: The maximum allowable value for the index. If the index 

exceeds this value, the carry bit is set and execution continues. If 
this parameter is omitted, then no bounds checking is performed. 

address table: A table of addresses used by the switch. Note that the 
address - 1 is used. This is because of the RTS instruction. 

* : If the asterisk is supplied as the fourth parameter, the macro will 
push the switch address but will not exit to it; execution will 
continue after the macro. 



.MACRO 


SWITCH 




.IF 


• •%v •<>••* • 


;If parami then 


LDA 


%1 


;Load A with index 


.ENDC 






.IF 


, ,o/,2' •<>•••• 


;If param2 then 


CMP 


#%2 + 1 


;Perform bounds check 


BCS 


$099 


; on switch i ndex 


.ENDC 






ASL 


A 




TAY 






LDA 




;6et switch address from the 


PHA 




;table and push onto stack 


LDA 


%3,Y 




PHA 






.IF 




;If paramA <> * then 


RTS 




;Exit to code 


.ENDC 




;Else Continue 



$099 

.ENDM 



The MOVEDATA Macro 

This macro moves up to 256 bytes within the assembly-language code/data 
space, in descending order. The A and X registers are destroyed; Y is not 
modified. 



Form: MOVEDATA (from), (to), (count) 



from: The byte address of the location from which the move is to occur. 

to: The byte address of the location to which the move is to occur. 

count: The number of bytes to move. If count is zero, the message 
ZERO IS A BAD COUNT is displayed. 



$99 



.MACRO 
-IF 

ZERO IS 

.ENDC 

LDX 

LDA 

STA 

DEX 

BNE 

.ENDM 



MOVEDATA 
BAD COUNT 
#%3 

%2-1 ,X 
$99 



; Loop unt i I done 



The MOVEDINC Macro 

This macro moves up to 255 bytes within the assembly-language code/data 
space, in ascending order. The A and X registers are destroyed; Y is not 
modified. 

Form: MOVEDINC (from), (to), (count) 

from: The byte address of the location from which the move is to occur. 

to: The byte address of the location to which the move is to occur. 

count: The number of bytes to move. If count is zero, the message 
ZERO IS A BAD COUNT is displayed. 

.MACRO MOVEDINC 

• IF %3"=» 
ZERO IS A BAD COUNT 
.ENDC 

LDX #0 

$99 LDA %1 , X 

STA %2,X 
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INX 

CPX #%3 

BCC $99 ;Loop until done 

.ENDM 

The BITBRANCH Macro 

This macro causes a branch if specified bits within a byte are on or off. The A 
register is destroyed; X and Y are unmodified. 

Form: BITBRNCH (data), <bitson>,<bitsoff>, (branch) 

data: The location of the byte whose bits are to be checked. 

bitson : The bits of this optional byte specify which bits of the data byte 
must be on if the branch is to occur. 

bitsoff : The bits of this optional byte specify which bits of the data byte 
must be off if the branch is to occur. 

branch: The address to which execution should branch if the bits of the 
data byte specified by bitson are on, and the bits specified by 
bitsoff are off . 

If the bits specified by bitson are not on, or if the bits specified by bitsoff are 
not off, the specified branch is not taken. You need not specify both bitson and 
bitsoff, but you must specify at least one of them, or the message no bits 
SPECIFIED will be displayed. 

.MACRO BITBRNCH 

.IF • 'P/oZ ••:=••• • 

.IF %3 • 
NO BITS SPECIFIED 
.ELSE 

LDA #%3 

AND %1 

BEQ %A 
.ENDC 
.ELSE 

LDA #%2 

AND %1 

EOR #%2 

.IF 0/^3 ' 

BEQ %4 



(•Generate an error 



;Bits off only 



; B i t s on only 




I 



I 



.ELSE 



LDA 



$099 

#%3 



AND 



%1 



;Both conditions have been met 



$099 



.ENDC 



.ENDC 



The NOTBITBR Macro 

This macro is the converse of macro BITBRNCH. It causes a branch If 
specified bits within a byte are not on or off. The A register is destroyed; X and 
Y are unmodified. 

Form : NOBITBR (data) , < bitson > , < bitsof f > . (branch) 

data: The location of the byte whose bits are to be checked. 

bitson : The bits of this optional byte specify which bits of the data byte 
must be on If the branch Is not to occur. 

bitsof f: The bits of this optional byte specify which bits of the data byte 
must be off If the branch Is not to occur. 

branch : The address to which execution should branch if the bits of the 
data byte specified by bitson are not all on, and the bits specified 
by bitsoff are not all off. 

If any one of the bits specified by bitson are not on, or if any one of the bits 
specified by bitsoff are not off, the specified branch is taken. If the bits 
specified by bitson are on, and the bits specified by bitsoff are off, the 
specified branch is not taken, and execution continues with the next 
Instruction. You need not specify both bitson and bitsoff, but you must specify 
atleastoneof them, or the message NO bits specified wlllbedlsplayed. 

.MACRO NOTBITBR 




NO BITS SPECIFIED 



;Generate an error 
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.ELSE 

IDA #%3 
AND %1 

BNE %4 ;Bi ts off only 

.ENDC 

.ELSE 

LDA #%2 

AND %1 

EOR #%2 

. I F » • I I , • • I I 

BNE %4 ;Bits on only 

.ELSE 

BNE %4 
LDA #%3 
AND %1 

BNE %4 ;Both conditions have been met 

.ENDC 

.ENDC 

.ENDM 



Equates for SOS Call Numbers 



REQUEST-SEG 


.EQU 


040 


FIND-SEG 


.EQU 


041 


CHANGE-.SEG 


.EQU 


042 


GET_SEG-.INFO 


.EQU 


043 


GET-SEG-NUM 


.EQU 


044 


RELEASE-SEG 


.EQU 


045 


SET- FENCE 


.EQU 


060 


GET-FENCE 


.EQU 


061 


SET-TIME 


.EQU 


062 


GET-TIME 


.EQU 


063 


GET-ANALOG 


.EQU 


064 


TERMINATE 


.EQU 


065 


D-STATUS 


.EQU 


082 


D-CONTROL 


.EQU 


083 


GET-DEV-NUM 


.EQU 


084 


D_INFO 


.EQU 


085 


CREATE 


.EQU 


0C0 


DESTROY 


.EQU 


0C1 


RENAME 


.EQU 


0C2 


SET- FILE- INFO 


.EQU 


0C3 
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FOU 


004 


\/ni 1 IMF 


FOU 


005 


QFT PRFFIY 


FOU 

. L. vjc W 


006 


r^FT PRFFiy 


FOU 


007 


nPFM 

\JrLLW 


FOU 


008 


MFWI IMF 

INlI VVL.Ii>iLl 


FOU 


009 




FOU 


0OA 


WRITF 
vvni 1 c 


FOU 


0OB 


pi n^F 


EOU 


000 


CI 1 IQU 

rLUon 


FOl 1 


00 D 


SET- MARK 


.EQU 


0OE 


GET-MARK 


.EQU 


0OF 


SET- EOF 


.EQU 


0D0 


GET- EOF 


.EQU 


0D1 


SET- LEVEL 


.EQU 


0D2 


GET- LEVEL 


.EQU 


0D3 




I 



^ Glossary 



The definitions given in this glossary are only those stated or implied in the text 
of this manual. Other definitions connected with different usages of the same 
terms are not given. An item appearing in the glossary is shown in boldface 
type when it first occurs in the text. 

activation record memory space on the program stack that stores the 
markstack, function value, passed parameters, and local variables for an 
active procedure. Activation records are created by procedure calls and 
removed as a procedure is terminated. 

Assembler directive statements placed in assembly-language programs 
that cause certain operations to be performed during program assembly. 
Assembler directives begin with a period, for example, .PROC . 

attribute table a table associated with each procedure that contains 
information needed to execute the procedure. Attribute tables grow toward 
lower addresses. 

automatic variable a variable for which space is allocated at the time the 
procedure declaring the variable is called. 

bank a unit of memory of 32768 contiguous bytes. 

BASE BASE procedure pointer. A 1 6-bit pointer on zero page that points to 
the MSSTAT field of the activation record of the most recently invoked base 
procedure. See XBASE. 

base procedure ^ procedure of the Pascal system at lexical level or - 1 . 
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base-relative relocation table a table of addresses, within an assembly- 
language procedure , each address to be relocated relative to the address 
contained in the BASE psuedo-register. 

big a P-machine instruction parameter that is one-byte long when used to 
represent values in the range through 127, and two-bytes long when used 
to represent values in the range 1 28 through 32767. 

BIOS the Basic I/O System of the interpreter; it handles all low level 
Pascal I/O. 

block a unit of storage of 51 2 contiguous bytes. 

blocic boundary the boundary between byte 5 1 1 of one block and byte 
of the next block. 

byte eight bits of data. 

byte-aligned an instruction or structure starting at any byte, not necessarily 
an even-numbered byte (see word-aligned). 

codefile a file containing a segment dictionary and code segments. 

code part a portion of a code segment that consists of a group of 
procedures together with descriptive information about the procedures (the 
procedure dictionary). 

code segment a portion of a codefile containing P-code and/or native code. 
Code segments may have three parts: interface text, code part, and Linker 
information. 

Compiler COMMENT option a Compiler option that allows you to specify a 
comment to be placed in the segment dictionary of a codefile. 

data area the upper addresses of an activation record that contain space for 
local variables, passed parameters, and returned function value of a 
procedure. 

data segment a portion of memory set aside at execution time as storage 
space for data of intrinsic units. In disk codefiles, data segments are simply an 
entry in the segment dictionary, as they have no interface text, code part, or 
Linker information. 



declaration a Pascal construct that is used to announce the attributes of an 
identifier. 

device a piece of hardware used for data input or output. A disk drive, video 
screen, and speal<er are all commonly-used Apple III devices. 

device driver the software interface to a device that enables the Apple III to 
communicate with that device. 

don't-care byte Represents a non-negative integer less than 1 28; thus it 
can be treated as SB (signed byte) or UB (unsigned byte). 

dynamic chain a series of dynamic links. The dynamic chain describes the 
"route" by which a procedure was called. 

dynamic linic a pointer in a called procedure's markstack that points to the 
markstack of the calling procedure. 

dynamic variable a variable explicitly allocated by the program . Dynamic 
variables are allocated on the heap. (Contrast with automatic variable). 

enhanced indirect addressing an addressing method used to extend the 
Apple III memory addressing beyond 64K bytes. 

evaluation stacl( a data structure located on the user stack page. Used to 
pass parameters, to return function values, and as an operand source for 
many P-machine instructions. The evaluation stack grows downward. 

execution time the period of time during which a program is running. 

EXTERNAL function a declaration of a separate function. The declaration 
occurs in the calling procedure, and the actual native code occurs in a 
separate function. 

EXTERNAL procedure a declaration of a separate procedure. The 
declaration occurs in the calling procedure, and the actual native code occurs 
in a separate procedure. 

extra code space the portion of memory that is not occupied by SOS, the 
interpreter, BIOS, device drivers, the program stack-heap, or graphics space. 
3ode is automatically loaded in extra code space if any is available. 
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function a procedure that returns a value. 

global an entity accessible to all procedures within the scope of the 
procedure that declares it. See the Apple III Pascal Programmer's Manual ior a 
discussion of scope. 

global procedure a procedure of lexical level 0. 

heap part of the Apple III memory space used by the Pascal operating 
system to store dynamic variables. The heap grows toward the stack. 

high byte bits 8 to 1 5 of a word. 

host program a program in which other units or assembly procedures may 
be used. 

host program global data area the data area in the host program's global 
activation record that holds variables declared at the outermost lexical level of 
the host program (level -1 or 0). 

IMPLEMENTATION the portion of a unit following the INTERFACE. The 
IMPLEMENTATION contains declarations of private constants, types, and 
variables, private procedures, and functions, and the actual P-code of the 
procedures and functions declared in the INTERFACE. 

interface text the portion of a code segment that contains the ASCII text of 
the INTERFACE in the source text of a unit. 

INTERFACE the portion of a unit following the unit heading. The INTERFACE 
contains declarations of constants, types, variables, procedures, and 
functions that are made available to programs that USE the unit. 

intrinsic unit a unit whose code remains in its library codefile until the host 
program is executed. The Linl<er is not needed for intrinsic units; they are 
"prelinked." 

interpreter-relative relocation table a table of addresses, within an 
assembly-language procedure, each address to be relocated relative to a 
table within the interpreter. 
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IPC Interpreter Program Counter. A pointer on zero page that contains the 
address of the next instruction to be executed in the currently executing 
procedure. See XIPC. 

JTAB Jump TABIe pointer. A 1 6-bit pointer on zero page that points to the 
highest word of the attribute table of the currently executing procedure. See 
XJTAB. 

jump table a section of self-relative pointers to addresses within the 
procedure code used by jump instructions. Jump tables are located at the 
bottom of attribute tables. 

KP program stacK Pointer. A 1 6-bit pointer on zero page that points to the 
banl<-pair address of the current top of the program stack. See XKP. 

label an identifier. 

lexical level the level of procedure nesting within a program . The user 
program is lexical level 0; a procedure nested n levels deep within the user 
program has lexical level n. 

LIBMAP utility program a Pascal program that creates a Map textfile of 
Linker information, interface text, procedures, and functions for each segment 
in a library. 

Librarian a Pascal system program used to combine separately compiled or 
assembled codefiles into a single codefile or library file. 

library file a codefile containing intrinsic units, regular units, and/or external 
assembly-language procedures that can be used by a host program. 

library name file an ASCII file that contains one to five names of library files 
used by a host program. 

linked file a codefile that results from linking a host program segment with 
its referenced units and separate procedures and functions. 

Linker a system program used to incorporate separately compiled or 
assembled procedures into a host program. 
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Linker information the portion of a code segment that enables the Linker 
to resolve references and definitions of identifiers between separately 
compiled or assembled code. 

linicer information type a record within Linker information that indicates the 
specific kind of reference or declaration that the Linker must resolve. 

local entity an entity accessible only to the specific procedure within which 
it was declared. 

LONGINTIO a standard library unit that provides long integer arithmetic 
operations and the built-in STR function. 

low byte bits to 7 of a word. 

maciiine type the kind of microprocessor, for example, 6502. 

main procedure the lowest level procedure in a segment. 

marlcstack the lower part of an activation record that contains addressing 
context information and information on a calling procedure's environment. 

MP Markstack Pointer. A 1 6-bit pointer on zero page that holds the address 
of the MSSTAT field in the topmost markstack on the program stack. See 
XMP. 

native code assembled code for a microprocessor. 

NEXTSEG Compiler option a Compiler option that allows you to specify 
the segment number of the next regular unit, SEGMENT procedure, or 
SEGMENT function encountered by the Compiler. 

NP New Pointer. 1 6-bit pointer on zero page that points to the local bank-pair 
address of the current top of the heap (one byte above the last byte in use). 
See XNP. 

operand a single value, such as a constant, variable, reference, or function 
call. 



page a unit of storage comprising two blocks, or 1 024 contiguous bytes. 




PASCALiO a standard library unit tliat holds the SEEK, WRITE, WRITELN, 
READ, and READLN procedures. 

POINTERLIST a list of pointers in Linker information, each of which points to 
a location within the code segment where there is a reference to a variable, 
identifier, or constant that must be fixed up by the Linker. 

private an entity held in the global data area, but not accessible to the user 
program. 

procedure a section of procedure code with an accompanying attribute 
table. The term procedure is used to refer to the main program, any 
procedure, or any function. 

procedure code a sequence of native code or P-code instructions. 

procedure dictionary the upper section of a segment's code part, 
containing a list of pointers to the procedures in the code part. 

procedure number a number used to refer to a specific procedure. 

procedure-relative relocation table a table of addresses, within an 
assembly-language procedure , each to be relocated relative to the lowest 
address in the procedure. 

program library a library file with intrinsic units only. 

program stack a portion of memory used to store automatic variables, 
bookkeeping information about procedure and function calls, and code, if 
there is no available extra code space. 

psuedo-code or P-code the compiled form of a Pascal program . Psuedo- 
code is a machine-independent intermediate code that is interpreted by a 
specific machine-dependent interpreter. 

pseudo-machine or P-machine a software-emulated machine that 
executes P-code as its native code. The P-machine has an evaluation stack, 
several registers, and a user memory. 

psuedo-register a P-machine pointer composed of one word on zero page, 
and an X-byte on X-page (except for the SP register). 
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regular unit a unit whose code is separately compiled and combined with 
the host program's codefile by the Linker. 

relocation table a sequence of records that contain information necessary 
to relocate any relocatable addresses, within a native-code procedure, 
whenever the segment containing the procedure is loaded into memory. 

SEG SEGment pointer. A 1 6-bit pointer on zero page that holds the local 
bank-pair address of the highest word of the procedure dictionary of the 
segment to which the currently executing procedure belongs. See XSEG. 

segment a section of a Pascal program that can be swapped in or out of 
memory as required for operation. 

segment dictionary block of a codefile that contains information needed 
by the Pascal system to load and execute the segments in the codefile. 

SEGIMENT function a function that comprises its own unique segment. The 
code of SEGMENT functions is not loaded into memory until the function is 
called; as soon as it terminates, the space occupied by the code can be used 
for something else. 

segment number a unique number assigned to each segment. Used as an 
index into the segment table. 

SEGIMENT procedure a procedure that comprises its own unique segment. 
The code of SEGMENT procedures is not loaded into memory until the 
procedure is called; as soon as it terminates, the space occupied by the code 
can be used for something else. 

segment-relative relocation table a table of addresses, within an 
assembly-language procedure, each to be relocated relative to the lowest 
address in the segment. 

segment table a section of the higher addresses of SYSCOM that 
comprise a list containing information needed by the P-machine to read code 
segments into memory or to allocate space for data segments. 

self-relative pointer a pointer that points to an address, relative to the 
location of itself. To find the address referred to by a self-relative pointer, 
subtract the pointer from the address of its location. 
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separate function a separately-compiled assembly-language function in a 
library. Separate functions must be defined as external functions in the calling 
procedure. 

separate procedure a separately-compiled assembly-language procedure 
in a library. Separate procedures must be defined as external procedures in 
the calling procedure. 

slot one of the 1 6 entries in a segment dictionary. There is one slot for each 
segment in the codefile. 

SP evaluation Stack Pointer. An 8-bit pointer to the current top of the 
evaluation stack. It is actually the Apple III hardware stack pointer. 

stack see program stack. 

stack/heap space a portion of memory used exclusively by the program 
stack and heap. 

static cliain a series of static links. A static chain describes the lexical 
nesting levels of a procedure. 

static iink a pointer in a called procedure's markstack that points to the 
markstack of the procedure's lexical parent. 

STRP STRing Pointer. A 1 6-bit pointer on zero page that points to the bank- 
pair address of the top of the linked list of packed arrays of characters and 
strings on the stack. See XSTRP. 

SYSCOI\/l a section of memory on the stack used by the operating system 
and the P-machine to exchange information. 

SYSTEI^/I.LIBRARY f lie a library file that contains a group of separately- 
compiled Pascal system procedures and functions. 

textfile a file containing human-readable text, such as a source program. 

tos the operand on the top of the evaluation stack. 

unit a collection of procedures that are separately compiled into libraries and 
then invoked as modular components of a user program. 
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unit info the last ten characters in an interface text, necessary for the 
Compiler to compile a code segment that uses the interface text. 

unlinlced file a file that has not been linked with its calling procedure and 
procedures that it calls. 

user memory the portion of memory not occupied by SOS, the interpreter, 
BIOS, and device drivers. 

user program the main procedure of segment number 1 . 

user program global data area an area of memory that holds variables 
declared at the outermost lexical level of the user program (level 0). 

word 1 6 bits or two bytes, of which the lower, even-address byte is least 
significant on the 6502. 

word-aligned an instruction or structure starting at an even byte (see byte- 
aligned). 

XBASE BASE procedure pointer. A pointer on X-page that contains the 
number of the bank-pair for the MSSTAT field of the activation record of the 
most recently invoked base procedure. See BASE. 

X-byte a byte on X-page, used to facilitate enhanced indirect addressing. 
Also termed the eXtension-byte. 

XIPC Interpreter Program Counter. A pointer on X-page that contains the 
number of the bank pair for the address of the next instruction to be executed 
in the currently executing procedure. See IPC. 

XJTAB Jump TABIe pointer. A pointer on X-page that contains the number of 
the bank pair for the highest word of the attribute table in the procedure code 
of the currently executing procedure. See JTAB. 

XKP program stacK Pointer. A pointer on X-page that contains the number of 
the bank-pair for the current top of the program stack. See KP. 



XMP Markstack Pointer. A pointer on X-page that contains the number of the 
bank-pair for the MSSTAT field in the topmost markstack on the program stack. 
See MP. 

XNP New Pointer. A pointer on X-page that contains the number of the bank- 
pair for the current top of the heap (one byte above the last byte in use). See 
NP. 

X-page locations $1 600 through $1 6FF. Also called the extension page. 
The X-bytes of the system psuedo-registers reside here. 

XSEG SEGment pointer. A pointer on X-page that contains the number of the 
bank-pair for the highest word of the procedure dictionary of the segment to 
which the currently executing procedure belongs. See SEG. 

XSTRP STRing Pointer. A pointer on X-page that contains the number of the 
bank-pair for the top of the linked list of packed arrays of characters and 
strings on the stack. See STRP. 

zero page locations $00 through $FF. The system psuedo-registers reside 
here. 
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